Gestire i FlowStream con l’API di Flow

Flow · flow@11.1 flowflowstreamapiimportexportnotify

Tutto ciò che fa l’editor passa da un unico endpoint JSON: POST /fapi/ con il corpo { "schema": "<name>", "data": { ... } } (le rotte API di Total.js, vedi rotte API). L’indirizzo /fapi/ deriva dalla riga $api : /fapi/ del file config. Ogni chiamata tranne l’accesso richiede il cookie di sessione; senza di esso la risposta è 401: Unauthorized.

Queste chiamate sono state provate anche su un Flow 11.1 locale (Node.js 24 e total5@0.0.19) mentre scrivevamo questa pagina.

Accedere

Auth|login riceve login e password e risponde {"success":true} con il cookie di sessione. Una coppia errata risponde Invalid credentials.

curl -c cookie.txt -X POST http://localhost:8000/fapi/ \
  -H 'content-type: application/json' \
  -d '{"schema":"Auth|login","data":{"login":"<your login>","password":"<your password>"}}'

Le chiamate successive usano -b cookie.txt.

Le chiamate

`schema`	`data`	Cosa fa
`Streams`	nessuno	l’elenco dei FlowStream con `id`, `name`, `group`, `author`, `version`, `proxypath`, `size` e le `stats` in tempo reale di quelli in esecuzione
`Streams\`	save	`name`, e facoltativamente `author`, `version`, `icon`, `color`, `group`, `url`, `reference`, `readme`, `memory`, `cloning`, `proxypath`, `proxytimeout`	crea un flusso quando manca `id` (si controlla il permesso create), altrimenti aggiorna il flusso con quell’`id` e lo riavvia
`Streams\`	read	`id`	le proprietà di un flusso
`Streams\`	raw	`id`	l’intero oggetto del flusso, con il suo design
`Streams\`	export	`id`	il flusso come testo JSON in `value`, senza i campi interni (`unixsocket`, `env`, `import`, `worker`, `asfiles`)
`Streams\`	import	`data` (il testo JSON)	crea un nuovo flusso da un’esportazione (fino a 10 MB), con un nuovo `id`; un `proxypath` ripetuto viene sostituito con uno casuale; risponde `{"success":true,"value":"<id>"}`
`Streams\`	pause	`id`, `is` (`true` o `false`)	mette in pausa o riprende un flusso in esecuzione
`Streams\`	restart	`id`	riavvia il flusso
`Streams\`	remove	`id`	rimuove il flusso e la sua cartella (si controlla il permesso remove)
`Streams\`	stats	nessuno	i totali dell’installazione: versioni di Node.js, Total.js e Flow, messaggi, in attesa, memoria e connessioni
`Variables\`	read / `Variables\`	save	`id` (facoltativo), `data`	le variabili di un flusso, oppure le variabili globali quando `id` è vuoto; il salvataggio le invia ai flussi in esecuzione
`Console\`	read / `Console\`	clear	nessuno	la console dell’applicazione
`CDN\`	clear	nessuno	svuota la cache dei componenti dell’interfaccia scaricati
`Settings\`	read / `Settings\`	save	le impostazioni (vedi impostazioni e file)	solo per il super amministratore

Creare un flusso ed eseguirlo

Crealo, poi importa un design costruito nell’editor (un file JSON esportato) per avviarlo:

curl -b cookie.txt -X POST http://localhost:8000/fapi/ \
  -H 'content-type: application/json' \
  -d '{"schema":"Streams|save","data":{"name":"Demo","author":"Me"}}'

Un flusso esportato dall’editor porta con sé il suo design (i riquadri e le loro connessioni), i suoi components (il sorgente di ciascuno) e le sue variables.

Regole di `proxypath`

Un flusso può pubblicare rotte HTTP sotto un percorso proprio. Flow aggiunge le barre (demo diventa /demo/), rifiuta i percorsi che appartengono a Flow stesso (/, /cdn/, /fapi/, /private/, /flows/, /designer/, /parts/, /forms/, /css/, /js/, /fonts/, /panels/) con Proxy endpoint contains reserved path e rifiuta un percorso già usato da un altro flusso. proxytimeout è il tempo in secondi di attesa della risposta del flusso (il valore predefinito è 120).

Chiamate dall’esterno

Rotta	Uso
`GET` o `POST /notify/{id}/`	invia una notifica al flusso con quell’id (il corpo del POST è limitato a 1 MB); i componenti del flusso decidono cosa farne. Risponde `{"success":true}`
`+SOCKET /{id}/`	il WebSocket dell’editor per quel flusso (richiede la sessione)
`GET /private/?token=<token>`	elenca i file della cartella `private/` quando il token coincide con il `token` delle impostazioni; dieci token errati bloccano un indirizzo per 15 minuti
`+POST /update/`	aggiorna l’applicazione da un file `.bundle`; solo per la versione impacchettata

Tieni segreto il token, invia queste chiamate via HTTPS e metti Flow dietro un reverse proxy quando è raggiungibile da Internet.