Il repository ha un’architettura semplice e appropriata allo scopo, ma la pipeline Bruno → httpyac non è sufficientemente protetta. I rischi principali sono:
1. esempi versionati contenenti dati personali e identificativi di sessione;
2. conversioni httpyac incomplete o incompatibili;
3. tre file YAML non validi per il parser usato dal progetto;
4. test e quality gate quasi assenti.
Non serve una riscrittura generale: gli interventi possono essere incrementali e concentrati sui confini di conversione e validazione.
## Struttura e dipendenze
```text
bruno/workspace.yml
└─ 11 collezioni Bruno / 272 richieste circa
├─ folder e configurazioni ereditate
├─ ambienti e template dei segreti
├─ script Bruno
└─ esempi di request/response versionati
env.json.template
└─ setup-json-environment.ps1 → env.json locale
├─ update-bruno-environments.ps1 → .env Bruno
└─ update-httpyac-environments.ps1 → .env httpyac
bruno/
└─ generate-httpyac-requests.ps1 → autodocs/httpyac/ ignorato da Git
```
Dipendenze esterne:
- PowerShell ≥ 7.5;
- modulo `powershell-yaml`, disponibile localmente in versione 0.4.12;
- Bruno;
- estensione/CLI httpyac, non disponibile nella shell esaminata.
`tools/generate-http-requests/node_modules` è un artefatto locale ignorato, senza manifest versionato, e non costituisce una dipendenza riproducibile del repository.
## Quality gate e test attuali
Non risultano configurati CI, Pester, PSScriptAnalyzer, linting, coverage, scansione dei segreti o validazione automatica delle collezioni.
Controlli read-only eseguiti:
- 5 script PowerShell analizzati: zero errori sintattici;
- solo 4 delle 140 richieste mutative hanno una definizione di test a livello di richiesta;
- i 7 `.env.template` sono attualmente sincronizzati con `env.json.template`;
- nessuna suite automatizzata eseguibile;
- PSScriptAnalyzer e httpyac CLI non presenti.
Gli `examples` presenti nelle collezioni sono snapshot, non test. Lo stato complessivo dei gate è quindi **non superato/non definito**: manca un gate ufficiale e la validazione YAML già fallisce.
### 1. Dati personali e cookie di sessione negli esempi versionati
- **Severità/costo:** Critica / M
- **File/modulo:** esempi Bruno, per esempio [Get Items.yml](<C:/_Git/UniPR/api-collections/bruno/collections/IRIS GW (Gateway) REST API (v1)/WfItems/Get Items.yml:136>) e [Get UserInfo.yml](<C:/_Git/UniPR/api-collections/bruno/collections/Shibboleth/Get UserInfo.yml:76>).
- **Problema:** rilevati identificativi compatibili con codici fiscali in 38 file e cookie/session ID in 20 file. Alcuni esempi includono anche nomi e informazioni organizzative. Il file più grande supera 5,3 MB e 134.000 righe.
- **Rischio:** esposizione di dati personali, conservazione indefinita nella cronologia Git, possibili credenziali di sessione ancora utilizzabili, forte rumore nelle review.
- **Intervento minimo:** verificare l’origine dei dati, invalidare eventuali sessioni ancora valide, redigere o sostituire con dati sintetici gli esempi; limitare gli snapshot alle proprietà indispensabili.
- **Test prima dell’intervento:** introdurre una scansione ripetibile per cookie, token e identificativi personali con allowlist esplicita; registrare il baseline prima della redazione.
- **Impatto architetturale:** trasversale sulla politica di gestione degli esempi, senza nuovi layer.
### 2. Tre collezioni non sono parseabili dal convertitore dichiarato
- **Severità/costo:** Alta / S
- **File/modulo:** [Backoffice - Dashboard.yml](<C:/_Git/UniPR/api-collections/bruno/collections/elixForms API v2/Console UI/Backoffice - Dashboard.yml:125>), [Login - Backoffice.yml](<C:/_Git/UniPR/api-collections/bruno/collections/elixForms API v2/Console UI/Login - Backoffice.yml:172>), [Login - Gestione Schede.yml](<C:/_Git/UniPR/api-collections/bruno/collections/elixForms API v2/Console UI/Login - Gestione Schede.yml:140>).
- **Problema:** i literal block contengono righe iniziali whitespace-only che `powershell-yaml` rifiuta. Il generatore propaga l’errore da [Parse-Yaml](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:26).
- **Rischio:** generazione httpyac interrotta e output parziale o obsoleto.
- **Intervento minimo:** normalizzare quei blocchi e fare fallire il comando con un riepilogo completo dei file invalidi.
- **Test prima dell’intervento:** gate che esegua il parsing di tutti i YAML; fixture con il blocco problematico e verifica dell’errore diagnostico.
- **Impatto architetturale:** nessuno; rende affidabile il formato sorgente.
### 3. Script Bruno copiati in httpyac senza adattamento del runtime
- **Severità/costo:** Alta / M
- **File/modulo:** [Parse-HttpBlock](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:206) e [Build-RequestContent](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:738).
- **Problema:** 16 file `.http` generati contengono chiamate Bruno come `bru.setVar` e `res.getStatus()`. httpyac documenta invece oggetti quali `response`, `$global` ed `exports`; la copia verbatim attraversa impropriamente il confine tra due runtime diversi. [Documentazione ufficiale httpyac](https://httpyac.github.io/guide/scripting.html)
- **Rischio:** request apparentemente generate ma script e test non eseguibili.
- **Intervento minimo:** tradurre solo le API Bruno effettivamente usate oppure interrompere esplicitamente la conversione dei file non supportati, evitando output silenziosamente difettoso.
- **Test prima dell’intervento:** golden test per login, lettura risposta e salvataggio variabile; esecuzione del `.http` generato contro un endpoint mock.
- **Impatto architetturale:** importante sul boundary Bruno→httpyac, ma confinato all’adapter esistente.
### 4. I body `multipart-form` vengono ignorati
- **Severità/costo:** Alta / M
- **File/modulo:** [Build-RequestContent](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:693); richieste interessate includono [AJ Console - Save Object.yml](<C:/_Git/UniPR/api-collections/bruno/collections/elixForms API v2/Console UI/AJ Console - Save Object.yml:15>), [Backoffice - Create Group.yml](<C:/_Git/UniPR/api-collections/bruno/collections/elixForms API v2/Console UI/Backoffice - Create Group.yml:16>) e Login Backoffice.
- **Problema:** il generatore implementa soltanto `json` e `form-urlencoded`; per multipart emette una POST senza body e senza segnalazione.
- **Rischio:** operazioni mutative errate, con comportamento molto diverso dalla richiesta Bruno.
- **Intervento minimo:** supportare multipart per i campi realmente presenti oppure fallire esplicitamente indicando request e body type.
- **Test prima dell’intervento:** fixture multipart con campi testo, placeholder e caratteri speciali; confronto golden del body generato.
- **Impatto architetturale:** locale al convertitore.
### 5. Aree mutative quasi prive di protezione automatica
- **Severità/costo:** Alta / L
- **File/modulo:** soprattutto `Cambio stato e-o integrazione`, `Console UI`, ESSE3 e i 93 POST EFTL.
- **Problema:** soltanto 4 delle 140 richieste mutative analizzabili hanno test request-level; non esiste un comando CI che li esegua.
- **Rischio:** regressioni su cambio stato, clone, aggiornamenti, delete e autenticazione scoperte soltanto manualmente.
- **Intervento minimo:** partire da smoke/contract test per autenticazione e operazioni più distruttive, usando ambienti controllati o mock; non è necessario testare subito ogni snapshot.
- **Test prima dell’intervento:** definire una matrice minima per status, payload obbligatori, errori 4xx e assenza di effetti collaterali indesiderati.
- **Impatto architetturale:** introduce un gate, non un nuovo layer applicativo.
### 6. Serializzazione `.env` non round-trip safe
- **Severità/costo:** Alta / S
- **File/modulo:** [update-bruno-environments.ps1](C:/_Git/UniPR/api-collections/scripts/update-bruno-environments.ps1:29) e [update-httpyac-environments.ps1](C:/_Git/UniPR/api-collections/scripts/update-httpyac-environments.ps1:26).
- **Problema:** i valori contenenti `#` vengono quotati, ma il parser conserva le quote; una seconda esecuzione può produrre quote duplicate. Apici, newline e altri caratteri dotenv non vengono gestiti sistematicamente.
- **Rischio:** password e token validi diventano inutilizzabili senza errore esplicito.
- **Intervento minimo:** definire escaping e parsing simmetrici per il sottoinsieme dotenv supportato.
- **Test prima dell’intervento:** round-trip parametrico per `#`, apici, spazi, `=`, valori vuoti e `null`.
- **Impatto architetturale:** boundary dei segreti; nessun nuovo layer necessario.
### 7. Test errato e dead code nello script “owners”
- **Severità/costo:** Media / S
- **File/modulo:** [SCRIPT - Get Contracts with two or more owners.yml](<C:/_Git/UniPR/api-collections/bruno/collections/IRIS GW (Gateway) REST API (v1)/Contracts/SCRIPT - Get Contracts with two or more owners.yml:113>).
- **Problema:** l’output espone `ownersCount`, ma il test verifica `contributorCount` alla [riga 248](<C:/_Git/UniPR/api-collections/bruno/collections/IRIS GW (Gateway) REST API (v1)/Contracts/SCRIPT - Get Contracts with two or more owners.yml:248>). Il controllo `output.length >= 0` alla riga 258 è tautologico. Rimane inoltre un intero ramo contributor commentato e una funzione department non più utilizzata.
- **Rischio:** fallimenti ingannevoli o test che passano senza verificare l’aggregazione; manutenzione confusa.
- **Intervento minimo:** correggere la proprietà, usare una fixture non vuota e rimuovere il ramo commentato dopo aver verificato che non sia necessario.
- **Test prima dell’intervento:** dataset con zero, uno e più owners e paginazione multipla.
- **Impatto architetturale:** nessuno; elimina una conseguenza concreta del copy/paste.
### 8. Generatore troppo concentrato e accoppiato al nome della cartella EFTL
- **Problema:** 1.095 righe; `Build-RequestContent` è di 377 righe con circa 63 diramazioni. Il comportamento EFTL è attivato cercando `"EFTL processing"` nel percorso e sovrascrive indiscriminatamente il post-response script alle [righe 733–785](C:/_Git/UniPR/api-collections/scripts/generate-httpyac-requests.ps1:733). Inoltre `Parse-Workspace` reimplementa manualmente il parsing pur essendo già disponibile il parser YAML.
- **Rischio:** cambiamenti locali producono regressioni trasversali; rinominare una cartella cambia la semantica.
- **Intervento minimo:** aggiungere test di caratterizzazione e separare soltanto rendering di auth, body e script in funzioni pure; rendere esplicita la modalità EFTL nella configurazione.
- **Test prima dell’intervento:** golden test EFTL/non-EFTL, inclusi script senza marker o marker incompleti.
- **Impatto architetturale:** chiarisce il confine tra conversione generica e regola EFTL senza introdurre pattern ulteriori.
### 9. Duplicazione degli updater e variabili dipendenti da rami precedenti
- **Severità/costo:** Media / M
- **File/modulo:** i due `update-*-environments.ps1`, differenti per appena 15 aggiunte e 18 rimozioni.
- **Problema:** `$sectionKeys` viene inizializzata dentro il ramo che trova `.env.template`, ma può essere usata successivamente anche quando il template manca. La duplicazione rende facile correggere un solo updater.
- **Rischio:** chiavi mancanti, riuso accidentale dei valori dell’iterazione precedente e divergenza Bruno/httpyac.
- **Intervento minimo:** prima inizializzare sempre le chiavi; poi usare un’unica funzione parametrizzata per root e policy di esclusione.
- **Test prima dell’intervento:** template presente/assente, `.env` presente/assente, chiavi aggiunte/rimosse e valori `null`.
- **Impatto architetturale:** riduce duplicazione di conoscenza nella pipeline dei segreti.
### 10. Bootstrap delle dipendenze non riproducibile
- **Severità/costo:** Media / S
- **File/modulo:** [setup-tools.ps1](C:/_Git/UniPR/api-collections/scripts/setup-tools.ps1:1) e [README.md](C:/_Git/UniPR/api-collections/README.md:18).
- **Problema:** il README promette un tentativo di installazione, ma lo script esegue solo `Import-Module ... -ErrorAction SilentlyContinue` e comunica comunque successo. Non è dichiarata una versione compatibile.
- **Rischio:** una nuova workstation fallisce più avanti con diagnostica poco chiara.
- **Intervento minimo:** verificare presenza/versione e terminare con istruzioni esplicite oppure installare soltanto previo consenso dell’utente.
- **Test prima dell’intervento:** esecuzione in una sessione senza modulo e con versione incompatibile.
### 11. Copie e contenuti obsoleti aumentano il rischio di deriva
- **Severità/costo:** Bassa / S–M
- **File/modulo:** directory `OLD`, `Obsolete`, file `Get Items Copy.yml`/`Get ASNs Copy.yml` e due coppie di runner completamente identiche.
- **Problema:** duplicazione significativa e snapshot molto grandi; non è però dimostrabile dalla sola analisi statica che siano davvero inutilizzati.
- **Rischio:** correzioni applicate a una sola copia, review lente e crescita del repository.
- **Intervento minimo:** censire uso e ownership; eliminare solo copie confermate inutilizzate o documentarne esplicitamente lo scopo.
- **Test prima dell’intervento:** confronto comportamentale delle copie e verifica con gli utilizzatori.
- **Impatto architetturale:** nessuno; pulizia controllata, non refactoring speculativo.
## Invarianti consigliate
I futuri gate dovrebbero verificare almeno che:
- ogni YAML sia parseabile dal parser effettivamente usato;
- nessun body type venga ignorato silenziosamente;
- gli script attraversino Bruno→httpyac solo se tradotti o dichiarati compatibili;
- gli output generati siano prodotti in una directory temporanea e validati;
- i template dei segreti restino sincronizzati;
- esempi e snapshot non contengano credenziali o dati personali non autorizzati.
Non raccomando al momento un ADR formale: basterebbe documentare queste invarianti nel repository e automatizzarle.
Non ho letto il contenuto di `env.json`, non ho eseguito chiamate API e non ho lanciato script che scrivono output. `git status` e `git diff` sono rimasti vuoti: nessun file è stato modificato.
description:'possibili valori:VAL("Validata"), IMP("Importata"), IMPW("Impostata con warning"), KO("Rifiutata")'
- name:resultDescription
value:messaggio custom
value:""
description:descrizione esito processo esterno
disabled:true
- name:resultReceiptId
value:"999"
value:"123"
description:id pratica processo esterno di riferimento
- name:resultTimestamp
value:""
@@ -135,34 +136,8 @@ examples:
}
}
docs:|
# Acquisizione delle istanze elaborate da processo esterno
~~Scopo: per confermare che l'istanza é stata ricevuta e non andrà più trasmessa.~~
**(MA ASSOLUTAMENTE NO!)**
Empiricamente, sposta l'istanza in stato "Evasa" e impedisce la riapertura della stessa.
## Parametri importanti
- **outcome(*)** (esito del servizio): possibili valori:
- OK
- KO
- **resultCode(*)** (codice esito processo esterno): possibili valori:
- VAL("Validata")
- IMP("Importata")
- IMPW("Impostata con warning")
- KO("Rifiutata")
- **resultDescription** (descrizione esito processo esterno)
- **resultReceiptId(*)** (id pratica processo esterno di riferimento)
- **resultTimestamp**: (timestamp di riferimento dell'elaborazione pratica dal processo esterno): in formato standard ISO 8601; se non impostata viene inizializzata con la data/ora server corrente
- **properties** (mappa chiave,valore/i aggiuntivo/i in formato json): url-encoding richiesto in UTF-8
## Descrizione
Viene ritornato l'esito dell'operazione di storicizzazione su elixForms.
La ricezione di "ok" o "ko" provocherà una decisione nel workflow semplice (analogo a quello di elixFlow) in base a quanto disposto in elixForms per il modulo.
- Esempio="OK","VAL","..." imposta lo stato di workflow semplice corrispondente imposta lo step ad "evasa" notifica email
- Esempio="KO","KO","..." imposta lo stato di workflow semplice corrispondente non cambia lo stato dello step
The columns variable must be built like the following:
The elixRegisterResultColumns variable must be built like the following:
- variable must start with "columns;"
- add one "index=value" couple for every field in the SWF schema to be updated, where "index" is the name of the associated SWF schema field (e.g.: COL0003) and "value" is the string content to be used
- one index=value couple for every field in the SWF schema that must be updated, where index is the "name" of the schema field (e.g.: COL0003, if the field is found in the SWF schema) and the value is the string content that must be assigned
- each couple must be separated by a semi-period (\`;\` character)
For example, suppose the request has a SWF schema with ID 356 having:
For example, suppose the request has a SWF schema with ID 356, containing:
- State = COL0001
- Date = COL0002
@@ -124,8 +117,6 @@ docs: |-
If you want to change the CURRENT state's date and message values, you will put into the variable the following value:
`columns;[{"key":"COL0002","value":"31-03-2025"},{"key":"COL0004","value":"this is the new message"}]`
`COL0002=31-03-2025;COL0004=this is the new message`
Keep in mind that Bruno automatically encodes the parameter, so you may use spaces and other symbols (maybe?).
Keep in mind that Postman automatically encodes the parameter, so it's allowed to use spaces and other symbols (maybe?).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
pierpaolo.mammi