I workspace Structurizr divisi su più file ora si importano in Archyl

Alcuni workspace Structurizr non tengono quasi nulla in workspace.dsl. Un'intestazione, un blocco model e una colonna di righe !include, una per sistema, con il modello vero distribuito nei file a cui puntano.

Fino a questa settimana Archyl non poteva importarli. Il nostro articolo del 4 agosto sulla chiusura di Structurizr Cloud lo diceva in una riga: i workspace su più file andavano prima appiattiti. Questo escludeva i workspace che tengono ogni sistema nel proprio file. Structurizr Cloud chiude il 30 settembre, tra due settimane.

Ora puoi caricare il workspace come .zip, e Archyl risolve ogni !include rispetto ai file al suo interno.

Perché un singolo file non avrebbe mai funzionato

Prendi un workspace organizzato così:

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

con un file radice che si limita a cucire insieme i pezzi:

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

Carica o incolla quel file radice da solo e l'importer non ha nulla rispetto a cui risolvere i percorsi. Analizza quello che ha, salta ogni include e ti avvisa:

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

Gli avvisi sono corretti, e sono anche l'intero risultato: dentro non c'è nulla di quei sei file. Un singolo file .dsl autosufficiente si importa esattamente come prima. Lo zip serve per tutto il resto.

Comprimi la directory del workspace, non il repository

Se il tuo workspace usa !include, i file separati esistono da qualche parte come file. La documentazione sugli include di Structurizr descrive un include di file come "a single local file, specified by a relative path" — un singolo file locale, indicato tramite un percorso relativo. Quindi la copia che conta è su un disco o in Git, non nel cloud. Trova la directory che contiene workspace.dsl e comprimi quella.

Dall'interno della directory:

zip -r workspace.zip workspace.dsl model systems

Oppure, se il workspace sta in un repository, direttamente da un commit:

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

La distinzione conta perché l'archivio è limitato a 500 voci, e il conteggio viene verificato prima di filtrare qualsiasi cosa. Comprimi un intero repository con la sua cartella .git e puoi superare il limite prima che venga letto un solo file .dsl. Una cartella contenitore al primo livello dell'archivio va bene, perché gli include vengono risolti rispetto al file che esegue l'include.

Cosa succede quando lo carichi

Nella modale di importazione, il pulsante del tab Structurizr DSL ora dice Carica .dsl o .zip. Scegli un archivio e l'editor di codice viene sostituito da una scheda con nome e dimensione. Clicca su Valida e la scheda aggiunge il numero di file e il file radice scelto.

Funziona sia quando importi in un progetto esistente sia quando ne crei uno nuovo. Un nuovo progetto prende il nome dall'intestazione del workspace, quindi workspace "Payments Platform" { ... } può creare un progetto e un semplice workspace { ... } no.

Sul server, l'archivio attraversa quattro passaggi:

1. Scegliere la radice. workspace.dsl se l'archivio lo contiene, altrimenti il file .dsl meno profondo. Quando deve scegliere tra più file e nessuno si chiama workspace.dsl, un avviso indica il file usato.
2. Espandere gli include come testo, prima del parsing. Il contenuto del file incluso sostituisce la riga !include, lo stesso inlining che fa Structurizr. I percorsi sono relativi al file che include, quindi systems/index.dsl che include shared/platform.dsl trova systems/shared/platform.dsl.
3. Risolvere gli include di directory. !include systems porta dentro ogni file .dsl che si trova direttamente in systems/, in ordine di nome. Le sottodirectory non vengono esplorate.
4. Fermarsi ai bordi. Se un file finisce per includere se stesso, direttamente o tramite un altro file, il ciclo viene interrotto e segnalato. L'annidamento si ferma a 10 livelli.

Il workspace espanso passa poi per lo stesso importer Structurizr di un file singolo, con la stessa fedeltà e lo stesso elenco di avvisi per tutto ciò che salta.

Anche un include che non si può risolvere, come un file mancante o un percorso che punta fuori dall'archivio, diventa un avviso. Il resto del workspace viene importato comunque.

Gli include remoti sono rifiutati di proposito

Structurizr permette anche a !include di puntare a un URL HTTPS. Archyl non li segue. Risolverli permetterebbe a qualsiasi file caricato di far contattare ai nostri server un indirizzo a sua scelta, il che è un vettore di server-side request forgery, chiunque sia a caricarlo. La riga viene saltata con un avviso:

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

Se il file remoto contiene elementi del modello che ti servono, scaricalo nell'archivio e cambia la riga in un percorso relativo.

I limiti

Le voci il cui percorso tenta di uscire dall'archivio, tramite un percorso assoluto o segmenti .., vengono saltate con un avviso. Vengono tenuti solo i file di testo: .dsl, .md, .json, .yaml, .yml e .txt. Le immagini e tutto il resto vengono scartati senza avviso, dato che all'importer DSL non servono.

Cosa ancora non fa

La sincronizzazione Git non risolve gli include. La sincronizzazione del repository legge archyl.yaml, non un workspace Structurizr, quindi non c'è ancora un percorso con cui Archyl prenda un DSL su più file direttamente da un repository. Se il tuo DSL sta in Git, per ora il workflow è il comando git archive qui sopra.

Nient'altro è cambiato nella fedeltà a Structurizr. Layout, stili e deployment view non venivano importati prima e non vengono importati nemmeno da uno zip. Non c'è ancora neanche un percorso per workspace.json: Archyl legge testo DSL. Se ciò che apprezzi di più in Structurizr è il layout sistemato a mano, le opzioni dell'articolo sulla chiusura che ti tengono sugli strumenti di Structurizr restano la scelta migliore.

Prima del 30 settembre

1. Assicurati di avere i file sorgente. Un workspace diviso con !include è stato scritto come file, quindi trovali. Se qualcosa esiste solo nella copia cloud, come un layout ritoccato nel browser o documentazione scritta lì, l'articolo del 4 agosto spiega come tirarlo fuori.
2. Comprimi la directory che contiene workspace.dsl, non il repository che la circonda.
3. Carica e valida. Apri Import Project, o la modale di importazione dentro un progetto esistente, scegli Structurizr DSL, carica lo zip e clicca su Valida. Controlla il file radice scelto e leggi ogni avviso prima di importare.
4. Fai commit della directory in un repository se non ci sta già, così la prossima persona non dovrà cercarla sul tuo portatile.

Il comportamento completo dell'importer, comprese le regole sul nome dei nuovi progetti, è nella documentazione Architecture as Code. Per gli altri formati che Archyl importa, vedi importare progetti Structurizr, LikeC4 e IcePanel.