Flussi e automazione

Un flusso è un grafo orientato: nodi collegati da fili, percorsi a partire da un unico punto di partenza. Non è, di proposito, uno script con un ciclo. Quattro regole ne fissano la forma, e l’editor si rifiuta di pubblicare un disegno che ne rompa una, indicando il nodo sbagliato.

• Esattamente un innesco. Il nodo di innesco è l’unica entrata, ed è lui a decidere quali variabili esistono nel resto del disegno.
• Nessun ciclo. Un filo che riporta a un nodo da cui era uscito viene rifiutato, perché un flusso non sa attendere: un ciclo semplicemente non finirebbe mai.
• Ogni nodo deve essere raggiungibile dall’innesco. Un nodo rimasto appeso è un errore che una schermata non mostra, quindi è un errore al momento della pubblicazione.
• I rami vengono percorsi uno dopo l’altro, mai affiancati. Due rami contemporanei scriverebbero in state nello stesso istante, e il risultato dipenderebbe dal caso dell’orologio.

L’editor è una tela, e non ce n’è una seconda. Un flusso nuovo si apre subito su di essa, e un flusso che era una lista dritta di passi si apre come una catena dritta di nodi.

• La tavolozza contiene i dodici tipi di nodo. Basta un clic per posarne uno sulla tela, oppure lo si trascina nel punto desiderato.
• Un nodo si sposta trascinandolo per la sua intestazione. Tutto il resto del nodo è un comando e quindi non avvia un trascinamento.
• Un filo va da un punto di uscita a un punto di entrata. Si trascina dall’uno all’altro, oppure si fa clic prima sull’uscita e poi sull’entrata. Le due cose fanno lo stesso, e la seconda è la via da tastiera.
• Lasciare un filo nel vuoto non fa nulla. Per rimuoverne uno lo si seleziona e si preme Canc, oppure si usa la croce che porta sopra.
• Lo zoom va dal 50 al 200 per cento, Adatta mostra tutto il disegno e trascinando lo sfondo si sposta la vista. Non c’è una mappa in miniatura.

Dodici tipi, e l’elenco è breve di proposito. Ogni tipo è un pannello, nove traduzioni, un ramo nell’esecutore e una riga nella tabella di verità, quindi un tipo che si guadagna il posto vale più di uno che ci arriva quasi.

Cinque momenti, e quello che si sceglie non dice soltanto quando il flusso gira. Dice anche quali variabili esistono, quali il selettore propone e quali la piattaforma rifiuta di salvare. Un percorso che in quel momento non può esistere è un errore al salvataggio, e non una stringa vuota a metà esecuzione.

Ogni valore che un flusso può leggere viene da uno di questi gruppi. Il selettore dell’editor mostra i gruppi che esistono per l’innesco scelto, e nient’altro. Leggere un percorso sconosciuto è un errore e mai un valore vuoto: un presupposto sbagliato deve fare rumore.

Un nodo set scrive in state. Il suo valore è testo letterale, a meno che non si spunti la casella espressione; allora viene letto come modello, con le variabili di questa esecuzione già inserite.

• Quella casella è una scelta deliberata. Un valore che per caso contiene due graffe, un pezzo di Ansible o un frammento di Helm, continua a significare ciò che diceva. Nulla cambia senso a causa di una modifica che nessuno ha chiesto.
• Il linguaggio è solo uscita. Due graffe e un percorso, e nient’altro: niente assign, niente capture, niente ciclo, niente include. Ciò che sta sulla tela è ciò che ne esce, con i valori inseriti.
• Ci sono 46 filtri: testo, numeri, date, i pochi filtri di elenco che producono testo, e i propri quote, ini e ipoctet. Il selettore dell’editor li elenca. Due famiglie mancano di proposito, quelle che tirano a sorte e quelle che restituiscono un oggetto dove si voleva una parola.
• I segreti qui non sono disponibili, e nemmeno i frammenti riutilizzabili. Ciò che un nodo set scrive finisce nel resoconto dell’esecuzione, e un segreto lì non ha nulla da fare.

Un flusso può fermarsi e attendere una persona, e può percorrere gli stessi nodi più di una volta. Nessuna delle due cose era possibile finché un'esecuzione non poteva essere messa in pausa e risvegliata; quella coda ora esiste.

• Un nodo di approvazione ferma l'esecuzione, crea una richiesta e avvisa l'account. Rispondere richiede un diritto separato, così chi ha scritto il flusso non è automaticamente chi lo firma.
• Ogni richiesta porta un termine e ciò che accade senza risposta: continuare come approvato, continuare come rifiutato oppure terminare l'esecuzione come non applicabile. Non esiste una quarta scelta, perché un'esecuzione che attende per sempre è un'esecuzione di cui nessuno sente più parlare.
• Per ogni percorre la sua uscita del ciclo una volta per elemento di un elenco. Nel ciclo, state.loop contiene l'elemento corrente, la sua posizione e il totale.
• Nulla dall'esterno di un ciclo può essere collegato ai nodi al suo interno. Quei nodi vengono eseguiti a ogni giro e una notifica collegata a entrambi scriverebbe un messaggio per giro.
• Un passo di approvazione può anche inviare e-mail. Quella posta raggiunge solo i membri che possono decidere sulle approvazioni, non tutti quelli che vedono i flussi, e la notifica nel pannello viene scritta comunque.

Un’esecuzione ferma non è un’esecuzione fallita. Tre cose possono metterla da parte, e tutte e tre usano la stessa coda: un’approvazione, una pausa lunga e un sottoflusso il cui figlio a sua volta attende.

• Una pausa di mezzo minuto o meno attende semplicemente dentro la richiesta che l’ha avviata, ed è ciò che serve quando concede un attimo a un agente. Tutto ciò che dura di più mette da parte l’esecuzione, così l’ordine che l’ha avviata si conclude subito e il resto del flusso arriva dopo.
• Un sottoflusso esegue un altro flusso di questo account come un solo passo. Il suo esito determina l’uscita: un figlio riuscito, o che non ha trovato nulla da fare, prosegue su OK; uno fallito su Errore. Lo stato, l’esecuzione e il nome del flusso stanno in state.subflow.
• Un flusso non deve mai raggiungere sé stesso, né direttamente né tramite un altro flusso. Viene verificato al deploy, e il messaggio indica la catena trovata.
• I flussi possono chiamarsi al massimo su tre livelli. Poiché ogni flusso si modifica separatamente, quel limite viene verificato due volte: al deploy e mentre l’esecuzione procede davvero.

Un punto di ingresso webhook dà a un sistema esterno una URL tutta sua. Quel sistema invia JSON, il flusso dietro la URL gira, e la risposta è un codice di stato nudo. I punti di ingresso stanno sotto Script, nella scheda Webhook, e sono oggetti a sé: lo stesso punto di ingresso può puntare a un altro flusso senza che il mittente se ne accorga.

1. 01Creare il punto di ingresso e dargli un nome riconoscibile in seguito. La URL viene generata e non si può scegliere: 32 caratteri casuali, cioè 160 bit, quindi indovinarla non è una strategia.
2. 02Scegliere come il mittente si identifica, e copiare il segreto. Viene mostrato una sola volta e mai più; se va perso lo si rigenera, e allora cambia anche la URL.
3. 03Puntare il punto di ingresso a un flusso il cui innesco sia un webhook. Il punto di ingresso può esistere prima del flusso, e fino ad allora una richiesta viene accettata e riceve un 202 che non avvia nulla. È l’ordine in cui la gente costruisce davvero queste cose, quindi non è trattato come un errore.

La firma è la parola sha256, un segno di uguale e l’HMAC-SHA256 su esattamente i byte della marca temporale, di un punto e del corpo, in esadecimale minuscolo. Va in X-Provibr-Signature, e la marca temporale stessa va in X-Provibr-Timestamp, in secondi interi dall’epoca.

Una richiesta la cui marca temporale sia più vecchia di 300 secondi, o stia nel futuro, viene rifiutata con un 401. Quella finestra è una regola vera e non un ornamento, perché la marca temporale sta dentro il materiale firmato: una richiesta intercettata non si può rispedire domani incollandoci sopra una marca fresca.

Firmare una richiesta è una riga di openssl. Questo esempio invia un piccolo oggetto; il testo per il terminale resta in inglese di proposito, perché corrisponda a ciò che il terminale mostra.

# Sign the raw body together with the timestamp, then post it.
SECRET="$PROVIBR_WEBHOOK_SECRET"
BODY='{"reason":"maintenance","attempt":1}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -sS -X POST 'https://app.provibr.com/api/hooks/flows/<your-slug>' \
  -H 'Content-Type: application/json' \
  -H "X-Provibr-Timestamp: $TS" \
  -H "X-Provibr-Signature: sha256=$SIG" \
  --data "$BODY"

Ogni richiesta lascia una ricevuta, accettata o no: l’esito, lo stato restituito, l’indirizzo di partenza per intero e quanti byte sono stati letti davvero. Il corpo non viene mai conservato. Le ricevute spariscono dopo 90 giorni, prima delle esecuzioni stesse, perché un indirizzo di partenza è un dato personale di qualcuno che non è nostro cliente.

Due domande che si somigliano hanno qui due risposte diverse. Chi ha cambiato che cosa, e quando, è una revisione. Che cosa questa singola esecuzione abbia davvero percorso è una copia conservata sull’esecuzione stessa. Un’istantanea non può rispondere alla prima domanda e una revisione non può rispondere alla seconda, quindi esistono entrambe.

• Ogni pubblicazione scrive una revisione, anche una pubblicazione che non ha cambiato nulla. Il numero sale per flusso e non viene mai riusato.
• La differenza tra due revisioni è un elenco leggibile e non JSON grezzo: un nodo aggiunto, tolto o modificato con i campi nominati, un filo aggiunto o tolto. Dove sta un nodo sulla tela non è una modifica.
• Ripristinare non riavvolge. Riscrive il vecchio disegno come nuova revisione sopra la storia, con una nota su da dove veniva.
• Ogni esecuzione conserva il disegno che ha percorso. Modificare un flusso in seguito non riscrive mai ciò che un’esecuzione più vecchia ha fatto.
• Un’esecuzione ha una riga per ogni nodo visitato, con l’esito e l’uscita da cui è passata, e una riga per ogni nodo non visitato con il motivo. Non visitato è un fatto che vale la pena annotare, non un’assenza.
• L’elenco delle esecuzioni filtra per innesco, stato e revisione, e si esporta in CSV. L’esportazione si ferma a 5000 righe e lo dice dentro il file anziché finire in silenzio.

I modelli di script tengono accanto una storia propria: ogni versione salvata del contenuto, e una differenza riga per riga tra due qualsiasi di esse.