# Realtime Framework: applicazioni senza un proprio server API

Un database realtime condiviso al posto di un broker di code e di un server API. L’interfaccia scrive un task, un processo indipendente lo prende in carico e il risultato torna da solo sullo schermo.

## In breve

- Tipo: Framework proprio di Kol.ski
- Per chi: Team che costruiscono pannelli, form e automazioni con processi sulle proprie macchine
- Ambito: Modello di architettura, contratti dei dati, pattern dei worker
- Stato: In uso in produzione, versione 1.0 del contratto in preparazione

## Sfida

Un pannello operativo, un form o uno strumento di audit hanno bisogno di tre cose insieme: un’interfaccia che mostra lo stato in tempo reale, processi che svolgono il lavoro su macchine diverse e un modo perché l’una parli con gli altri. La risposta classica è un server API, una coda con un broker e un canale websocket: tre sistemi da mantenere prima che esista la prima funzionalità.

> Chi lo sta eseguendo adesso, ed è ancora vivo?

Nell’impostazione classica rispondere a questa domanda richiede un monitoring separato. Qui doveva derivare dall’architettura stessa.

## Soluzione

Tutto il sistema si basa su un unico Firebase Realtime Database con tre rami. Ogni partecipante, una persona nel browser e un processo sul server, è un attore: osserva i dati, prende in carico il lavoro e scrive il risultato.

### Task

L’interfaccia o un automatismo scrive un task nel ramo `queue`. Un worker lo prende in carico con una sola scrittura: il primo che riesce vince, gli altri vedono che il task è occupato.

### Stato

Il ramo `data` contiene lo stato corrente, che l’interfaccia e i processi guardano insieme. Il risultato compare sullo schermo senza polling.

### Attori

Nel ramo `actors` ogni processo e ogni scheda aperta riporta identità, versione, capacità e heartbeat. Si vede chi è in esecuzione e con quale codice.

### Permessi

Ogni worker ha le proprie credenziali e solo i permessi che il suo compito richiede. Non esiste una chiave unica per tutto.

## Risultato

| Numero | Significato |
| --- | --- |
| 3 | rami del database per l’intero sistema: task, stato, attori |
| 3 | host nella prima prova: un server, un laptop e un Raspberry Pi |
| 0 | broker di code e server API propri |
| 30 | secondi è la pausa più lunga tra gli heartbeat di un processo |

### Cosa funziona

- La prima prova su tre host: ciascuno vedeva gli altri ed eseguiva i task a lui indirizzati.
- Pannelli operativi in cui un clic nell’interfaccia avvia il lavoro su una macchina remota e l’avanzamento si vede in tempo reale.
- Form pubblici che cifrano i dati nel browser: al database arriva il testo cifrato e il worker lo decifra solo al momento dell’esecuzione. Così funziona il form di contatto di questo sito.
- Lunghi job analitici che pubblicano l’avanzamento parziale: fase, elemento corrente e contatore.
- Un nucleo comune dei worker: presa in carico dei task, heartbeat, segnalazione della versione e riga di comando in un’unica libreria.

### Prossimi passi

- Un ciclo di vita del task unificato in tutti i worker, con nuovi tentativi e recupero del lavoro dopo il guasto di un processo.
- Un archivio degli eventi accanto al database realtime, che conserva lo stato corrente e non la storia completa.
- Un test comparativo con le piattaforme pronte di code e workflow.

Realtime Framework non sostituisce i motori di esecuzione durevole come Temporal. Dove un processo lungo deve essere ripreso passo dopo passo dopo un guasto, sono loro la scelta giusta.

## Di cosa è fatto

Le parti del sistema non si parlano direttamente. L’unico punto di contatto è il database e il suo contratto dei dati.

| Parte | Cosa fa | Tecnologia |
| --- | --- | --- |
| Interfaccia | Sito statico con login che legge lo stato e scrive i task direttamente nel database | Firebase Hosting, Firebase Auth, JavaScript |
| Database realtime | Tre rami e regole di accesso: l’unico punto attraverso cui passano task e risultati | Firebase Realtime Database, regole di sicurezza |
| Worker | Processi separati su server, macchine virtuali e dispositivi edge, ciascuno con ruolo e credenziali propri | Go, Python, PM2, systemd |
| Nucleo | Libreria comune dei worker: coda, heartbeat, versione, configurazione e riga di comando | Go, JSON |

## Lezioni apprese

- La versione nell’heartbeat deve venire dalla build. Inserita a mano è invecchiata in silenzio e diversi processi riportavano un numero che non avevano.
- Prendere in carico un task è una scrittura, non una rimozione dalla coda. Un solo campo di stato invece dello spostamento dei record semplifica l’osservazione e la ricerca degli errori.
- L’interfaccia è un attore, non un client. Quando una scheda del browser ha un’identità e un heartbeat, persone e processi compaiono in un unico registro.
- Un database realtime è stato, non archivio. Storia e audit richiedono un livello separato, pianificato fin dall’inizio.

## Costruisci un pannello o un’automazione?

Progettiamo applicazioni con vista in tempo reale e processi sulle tue macchine, senza un backend pesante. Scrivici cosa vuoi costruire.

[Parliamo del tuo progetto](mailto:hi@kol.ski) · [Prenota 30 minuti](https://calendar.app.google/CJxZPq3FqabCDMS59) · [Progetti](https://kol.ski/it/progetti)