Framework e bundle applicativi — panoramica del progetto

Il problema: una modifica piccola può coinvolgere molti repository

Un cliente chiede una modifica alle fatture. Lo sviluppatore interviene sull’applicativo, su un modulo GenroPy legacy e su due package condivisi. Il risultato da collaudare non è un singolo file: è una combinazione precisa di quattro repository.

🧱

Framework stabile

La stessa immagine Genro viene distribuita a tutti i clienti e contiene ciò che deve essere comune.

📦

Applicazione separata

Ogni combinazione esatta di codice e dipendenze diventa un bundle autonomo.

👥

Collaudo selettivo

Mario e Luigi provano la modifica; tutti gli altri continuano a usare la versione precedente.

↩

Ritorno semplice

Se la nuova build non va bene, il gruppo torna a un bundle già noto senza ricostruire nulla.

L’idea chiave: l’immagine contiene la macchina che sa eseguire le applicazioni; il bundle contiene l’applicazione concreta da eseguire.

La mappa globale in una schermata

Ci sono due catene indipendenti che si incontrano sul server: la piattaforma produce l’immagine Framework; ogni applicazione produce i propri bundle.

piattaforma applicazione artefatti pronti coorte di collaudo

Le due catene hanno ritmi diversi: un aggiornamento Framework sostituisce l’immagine per tutti; un aggiornamento applicativo aggiunge un bundle e può riguardare soltanto un gruppo.

L’immagine Framework: la macchina comune

È un’immagine container riproducibile, pubblicata in un registry OCI e utilizzabile sia su un server tradizionale sia dentro Kubernetes. Non contiene l’applicazione del cliente.

Perché due Python?

Il Framework può evolvere

Il control plane può adottare una versione Python adatta al server senza imporla alle applicazioni.

I bundle hanno un contratto stabile

Tutti vengono costruiti per lo stesso Python worker e la stessa piattaforma.

Processi realmente separati

Commander e worker comunicano via socket: non condividono interprete, memoria o moduli importati.

Cambiamento	Conseguenza
Nuova build applicativa	Si produce un nuovo bundle; l’immagine Framework non cambia.
Nuovo Python del control plane	Si produce una nuova immagine; i bundle possono restare validi.
Nuovo Python dei worker	È un cambio di piattaforma: tutti i bundle vanno ricostruiti o ricollaudati.
Nuova versione Genro ASGI	Aggiornamento globale e coordinato dell’immagine, non per singolo gruppo.

Il bundle: una fotografia completa dell’applicazione

L’applicativo possiede il proprio repository e la propria CI. Il suo lock descrive i commit esatti di tutti i repository che formano quella build.

Un esempio di manifest leggibile

application: fatture
bundle_name: collaudo-fatture
build: "005"
source:
  tag: bundle/collaudo-fatture/005
  commit: 8ab31e...
worker_contract:
  python_abi: cp312
  runtime: genro-worker-P17
repositories:
  genropy: 71ac9f...
  package_contabilita: c19d02...
bundle_sha256: c7f1...

Il tag non basta: il manifest conserva sempre i commit e il checksum effettivi. Così “build 005” resta verificabile anche mesi dopo.

S3: un deposito semplice, leggibile e protetto

Le versioni applicative sono cartelle logiche con nomi espliciti. Il versioning nativo di S3 resta attivo come rete di sicurezza, non come nome principale della release.

Build mai sovrascritta

La CI fallisce se la destinazione esiste già. Ogni prefisso identifica contenuti immutabili.

Canale leggibile

collaudo.json è un piccolo puntatore che può avanzare o tornare indietro.

Cache locale per digest

Il server scarica, verifica ed estrae una sola volta ogni contenuto.

Dal canale alla cache

Risolvicollaudo → build 005

Scaricain area temporanea

Verificamanifest + SHA-256

Estraisenza esporre file parziali

Attivacache/sha256-c7f1

Il worker non scarica direttamente da S3. Riceve un percorso locale già verificato dal control plane.

I gruppi sono vivi: si aggiungono e si tolgono senza fermare il server

Un gruppo non è un’immagine container. È una scelta runtime: nome, bundle risolto, policy e insieme di worker equivalenti.

Aggiunta di un gruppo

RESOLVING→ FETCHING→ VERIFYING→ WARMING→ ACTIVE

Aggiornamento dello stesso nome logico

# Vista concettuale — non è ancora un’API implementata
collaudo-fatture · generazione 3 · build 004 · ACTIVE
collaudo-fatture · generazione 4 · build 005 · WARMING

# Solo dopo la verifica:
generazione 4 → ACTIVE
generazione 3 → DRAINING → REMOVED

Regola di sicurezza: worker di build diverse non devono convivere nella stessa generazione. Il nome resta uguale, ma il contenuto fisico cambia attraverso una sostituzione controllata.

Un esempio completo: la modifica provata da Mario e Luigi

Questa storia copre sia il collaudo iterativo sia la possibile trasformazione della modifica in una vera release.

1 · Richiestanuovo calcolo fattura

2 · Sviluppo4 repository modificati

3 · Tagcollaudo-fatture/004

4 · CItest + bundle

5 · S3build immutabile

La correzione continua

# Tag sorgente progressivi; nome logico invariato
bundle/collaudo-fatture/004  → S3 …/collaudo-fatture/004/
bundle/collaudo-fatture/005  → S3 …/collaudo-fatture/005/
bundle/collaudo-fatture/006  → S3 …/collaudo-fatture/006/

gruppo visibile: collaudo-fatture
build effettiva: checksum sempre esplicito

Una modifica sperimentale e una release vera usano lo stesso meccanismo. Cambiano soltanto durata, ampiezza della coorte e decisione finale di promozione.

Compatibile con Kubernetes, senza delegargli le decisioni applicative

Kubernetes esegue e sorveglia l’immagine Framework. Genro continua a sapere quali utenti appartengono a quali gruppi e quali worker devono eseguire un bundle.

Kubernetes decide	Genro decide
Quale immagine Framework eseguire	Quale bundle usa ciascun gruppo
Avvio, riavvio e salute del Pod	Quanti worker applicativi servono
Risorse, rete e storage del container	Dove vive l’utente e quando cambia gruppo
Distribuzione infrastrutturale	Warm-up, drain, promozione e rollback applicativi

Limite dichiarato: il primo progetto può funzionare in un singolo Pod. Più Pod coordinati richiedono directory condivisa, lease e fencing: appartengono alla successiva architettura distribuita, non vanno finti in questa fase.

Cosa esiste già e cosa deve costruire il progetto

Il nuovo core di Genro ASGI ha già le fondamenta del processo worker e dell’affinità utente. La distribuzione dei bundle e il lifecycle dinamico non sono ancora implementati.

● Esiste oggi nel nuovo core

configurazione per gruppo;
interprete, entry module e worker class per gruppo;
processi worker collegati via socket;
avvio e arresto dei worker;
memoria dell’assegnazione utente → gruppo;
gruppo predefinito per i nuovi utenti;
affinità dell’utente al proprio gruppo.

● Deve essere progettato e implementato

formato definitivo del bundle;
risoluzione S3 e cache transazionale;
caricamento isolato del bundle nel worker;
ambiente pulito fra i due Python;
API pubblica add/refresh/remove group;
generazioni interne del gruppo;
gestione della coorte e promozione;
identità del bundle nella presentazione del worker.

Il collaudo cresce per prove piccole

Fase	Domanda a cui risponde	Prova concreta
B0 · Formato	Il bundle è davvero autonomo?	Due bundle con stessi moduli e risultati diversi.
B1 · Due Python	Control e worker sono davvero isolati?	Commander su Python A, worker su Python B.
B2 · S3	Un contenuto parziale può diventare visibile?	Checksum errato, download interrotto, cache concorrente.
B3 · Gruppi vivi	La produzione resta attiva?	Aggiunta e rimozione del gruppo di collaudo.
B4 · Revisioni	Possiamo correggere più volte?	004 → 005 → 006, guasto e rollback.
B5 · Promozione	Promuoviamo proprio ciò che è stato testato?	Stesso SHA-256 dal collaudo alla produzione.

Il nuovo core non contiene ancora tutto il data plane GenroPy. Le prime prove useranno un worker diagnostico; il pilot cliente richiederà anche il completamento delle Macro 5 e 6.

Scheda rapida

Il vocabolario e le operazioni principali, senza gergo superfluo.

Concetti

Quando dico…	Intendo…
Immagine Framework	Il container comune con control runtime, worker runtime e dipendenze possedute dalla piattaforma.
Bundle	Una build immutabile dell’applicazione e delle sue dipendenze applicative.
Canale	Un nome mobile, come produzione o collaudo, che indica un bundle.
Gruppo	Un insieme vivo di worker equivalenti che usano lo stesso bundle risolto.
Generazione	Una incarnazione interna del gruppo, necessaria per sostituire il bundle senza modificarlo in uso.
Coorte	Gli utenti scelti per usare un gruppo, per esempio Mario e Luigi.
Worker Python	La versione Python comune con cui vengono eseguiti tutti i bundle.

Azioni

Voglio…	Il sistema deve…
Pubblicare una modifica	Taggare il repo applicativo, costruire in CI e creare un nuovo prefisso immutabile su S3.
Far provare una build	Aggiungere un gruppo, scaldare un worker e poi assegnare una coorte esplicita.
Correggere il collaudo	Creare una nuova build e sostituire la generazione del gruppo solo dopo il warm-up.
Ritirare il test	Impedire nuovi ingressi, gestire gli utenti residenti, fermare i worker e rimuovere il gruppo.
Promuovere	Associare la produzione allo stesso checksum già collaudato, senza ricostruirlo.
Tornare indietro	Riattivare un bundle precedente già verificato e conservato in cache/S3.
Aggiornare Genro ASGI	Produrre e distribuire globalmente una nuova immagine Framework.

Responsabilità

Sviluppatore applicativo

Blocca i commit, crea il tag, interpreta i test e pubblica il bundle tramite CI.

Genro ASGI

Verifica il bundle, governa cache, gruppi, worker, coorti e lifecycle.

S3

Conserva artefatti immutabili, manifest, checksum e puntatori di canale.

Sysop / Kubernetes

Distribuisce l’immagine, concede risorse e osserva il container; non sceglie gli utenti del gruppo.

Riassunto in una frase: Kubernetes porta il motore, S3 porta le applicazioni, Genro decide quale applicazione alimenta ogni gruppo di worker e quali utenti vi entrano.