Files
Febe/docs/guida/Sviluppo.md
T
Alby96andClaude Opus 5.5 483d57b89a Pulizia: dopo ogni esecuzione la cache se ne va solo se nessuno la usa da 24 ore
Alla fine di ogni lavoro «immagine», cioè a ogni push di ogni ramo,
«docker builder prune -f» senza filtro toglieva dal builder del demone
tutta la cache che nessuna immagine condivide, di qualunque età e di
tutti i progetti: gli strati intermedi e le cache montate che Encelado o
Mimante avevano usato mezz'ora prima. Alla cache di Febe non serviva
(stava nel builder dell'esecuzione, già tolto) e annullava la finestra
di 24 ore della pulizia del lunedì (rilievo della revisione).

Ora anche dopo ogni esecuzione «--filter until=24h», che BuildKit
confronta con l'ultimo uso: una costruzione che si ripete almeno una
volta al giorno ritrova la sua cache. Il compito chiedeva il comando
senza filtro; la scelta resta di Alberto, e per tornarci basta togliere
il filtro. Le immagini senza nome restano senza filtro, come prima.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 11:42:28 +02:00

16 KiB
Raw Blame History

Sviluppo

Febe è scritto in C# 14 su .NET 10, in un'unica soluzione (Febe.slnx). L'interfaccia è HTML, CSS e JavaScript senza framework né fase di build. La specifica è docs/SPECIFICA.md; le scelte prese strada facendo sono in docs/decisioni.md, lo stato del lavoro in docs/stato.md.

Due regole prima di tutto

  • Nessuna prova, script o verifica contatta Instagram (né Meta, né il loro CDN): si usa solo il sito di prova locale. Le prove dal vivo le lancia Alberto. Lo stesso vale per Telegram: le prove usano un gestore HTTP finto, mai api.telegram.org.
  • Dipendenze a elenco chiuso (Directory.Packages.props): Microsoft.Data.Sqlite, SkiaSharp (con le librerie native per Linux), Microsoft.Web.WebView2, MSTest. Tutto il resto viene dalla libreria di base di .NET.

Com'è fatto il repository

Cartella Che cosa c'è
src/Febe.Core Dominio e logica senza piattaforma: motore, Governatore, interruttore, ricette, lettori, libreria, importazione, avvisi (Alerts/)
src/Febe.Data SQLite, migrazioni come file SQL numerati, scrittore unico
src/Febe.Browser Client del protocollo DevTools, ChromiumProcessHost, gesti, cattura delle risposte, vista remota
src/Febe.Web API, eventi dal server, interfaccia in wwwroot/ incorporata nell'assembly (vedi src/Febe.Web/LEGGIMI.md)
src/Febe.Server L'eseguibile per Linux e Docker (febe), con la dimostrazione e la simulazione
src/Febe.Desktop L'eseguibile per Windows (WPF, WebView2)
tests/Febe.Tests Le prove (MSTest), con i campioni ripuliti in tests/campioni/
tools/Febe.SitoDiProva Il sito locale per le prove senza Instagram
tools/Febe.Sonda La sonda passiva per raccogliere i campioni
tools/schermate Le schermate dell'interfaccia per il confronto con i mockup
docker/ Dockerfile, compose.yml, entrypoint.sh, file di Chromium (criteri, profilo seccomp), modello di Unraid
docs/ Specifica, decisioni, stato, Docker, prove dal vivo, esiti della sonda, mockup, schermate, e questa guida (docs/guida/)

Compilare e provare

dotnet build Febe.slnx -warnaserror
dotnet test tests/Febe.Tests
dotnet test tests/Febe.Tests --filter "FullyQualifiedName~Febe.Tests.Alerts"
  • Gli avvisi del compilatore sono errori. Febe.Desktop si compila anche da Linux (EnableWindowsTargeting), ma gira solo su Windows.
  • Le prove con un browser vero cercano Chromium in FEBE_CHROMIUM (o nel PATH) e Xvfb nel PATH; se mancano risultano inconcludenti, non fallite. Lo stesso per le prove d'insieme del server (Febe.Tests.Server), che avviano la composizione vera contro il sito di prova.
  • Il motore si prova con un orologio virtuale e un seme fisso; le prove d'insieme con un orologio compresso (10×).
  • La prova Febe.Tests.Docs controlla che questa guida dica tutto ciò che la specifica chiede (§15) e che ogni collegamento fra le pagine porti a una pagina che esiste.

Da VS Code

La cartella .vscode/ prepara VS Code per Febe: estensioni consigliate (C# Dev Kit e C#), soluzione predefinita Febe.slnx, attività e configurazioni di debug. Ogni configurazione compila prima con l'attività compila (dotnet build Febe.slnx -warnaserror); gli errori del compilatore finiscono nel pannello Problemi.

Configurazione (Esegui e debug, F5) Che cosa fa
Febe per Windows · sito di prova Avvia il sito di prova come attività di sfondo (porte 8481 e 8482), poi Febe per Windows con --sito-di-prova http://127.0.0.1:8481 --accesso-di-prova --prima-sessione 30 --sviluppo; a fine debug ferma il sito
Sito di prova + Febe per Windows Il sito di prova nel debugger; quando è pronto parte anche Febe per Windows, che si ferma insieme al sito
Febe Server · dimostrazione (--demo) La dimostrazione su http://127.0.0.1:8480, che si apre da sola nel browser; l'interfaccia viene da src/Febe.Web/wwwroot (FEBE_INTERFACCIA): modifichi un file e ricarichi la pagina
Sito di prova Solo il sito di prova, nel debugger
Simulazione 30 giorni (prudente) --simula 30g --profilo prudente, con il resoconto nella Console di debug
Febe Server · sito di prova (solo Linux) Il server vero, con Chromium su Xvfb, contro il sito di prova: interfaccia su 127.0.0.1:8480, password prova (come root serve anche --senza-sandbox, e FEBE_CHROMIUM se Chromium non è nel PATH). Su Windows e macOS si ferma con un messaggio; anche con «Esegui comunque il debug» stampa solo l'aiuto
⚠ Febe per Windows · Instagram vero (dati veri) Febe senza opzioni: Instagram vero, %LOCALAPPDATA%\Febe e Immagini\Febe. Solo per le prove dal vivo di Alberto: chiede conferma, e una versione di sviluppo può aggiornare il database vero. Se Febe installato è aperto, prima esci da lui (menu dell'icona ▸ Esci): un solo Febe per cartella dei dati
  • Dati di sviluppo. Febe per Windows di sviluppo tiene dati e libreria in %USERPROFILE%\FebeSviluppo\<checkout>\dati e %USERPROFILE%\FebeSviluppo\<checkout>\libreria, dove <checkout> è il nome della cartella aperta in VS Code (per esempio Febe; il server su Linux in ~/FebeSviluppo/<checkout>): fuori dal repository e mai nella cartella vera. Una cartella per checkout perché su una cartella dei dati gira un Febe solo (un secondo avvio mostra il primo ed esce) e un database scritto da un ramo più nuovo non si apre con una versione più vecchia. Con Febe chiuso si possono cancellare quando vuoi.
  • Chiudendo la finestra Febe resta nell'area di notifica e il debug continua: per finire, menu dell'icona ▸ Esci oppure Maiusc+F5. Finché Febe gira, compila non può sovrascrivere Febe.exe.
  • Il sito di prova usa sempre le porte 8481 e 8482, come attività e come configurazione: uno alla volta.
  • Se il sito di prova si ferma prima di Febe (terminale chiuso a mano, un guasto, oppure porta occupata e «Esegui comunque il debug»), a fine debug VS Code apre l'elenco delle attività da terminare, con «Termina tutte»: premi Esc. Con «Sito di prova + Febe per Windows» non succede, perché lì il sito sta nel debugger e non c'è un'attività da chiudere.
  • Registro. Nella Console di debug compaiono le righe del sito di prova, della dimostrazione, della simulazione e del server. Febe per Windows non ha una console: lì mostra solo i messaggi del debugger, e il suo registro sta nella cartella dei dati, %USERPROFILE%\FebeSviluppo\<checkout>\dati\registro\febe-AAAA-MM-GG.log (con il profilo di launchSettings.json, in FebeSviluppo\comune\dati\registro). Lì si leggono «Interfaccia sulla porta N», lo stato del browser di Febe e gli errori.
  • Le configurazioni usano la Console di debug e le attività partono senza shell: il terminale integrato carica il profilo di PowerShell, che può mettere davanti un altro .NET (per esempio quello di un ambiente conda), e allora dotnet non trova l'SDK 10 o Febe non parte («You must install or update .NET»). Se nel terminale dotnet --list-sdks non mostra il 10, usa le attività, Git Bash oppure conda deactivate.
  • Fermata dal debugger, la dimostrazione non cancella la sua cartella temporanea (febe-dimostrazione-…, una trentina di MB): da VS Code su Windows finisce in %USERPROFILE%\FebeSviluppo\<checkout>\temporanei, che si svuota quando vuoi. Con dotnet run --project src/Febe.Server -- --demo in un terminale, Ctrl+C la chiude in ordine e la cancella.
  • Fuori da queste configurazioni (dotnet run --project src/Febe.Desktop, il pulsante ▷ «Debug project associated with this file» e «Start New Instance» del C# Dev Kit, le sue configurazioni automatiche «C#: …») Febe per Windows prende l'unico profilo di src/Febe.Desktop/Properties/launchSettings.json: sito di prova su http://127.0.0.1:8481 (da avviare a parte, per esempio con l'attività sito di prova) e dati in %USERPROFILE%\FebeSviluppo\comune, la stessa cartella per tutti i checkout. Instagram vero da un terminale solo con dotnet run --project src/Febe.Desktop --no-launch-profile: come la configurazione ⚠, è per le prove dal vivo di Alberto.
  • Attività (Terminale ▸ Esegui attività): compila, prove (dotnet test tests/Febe.Tests), prove Windows (dotnet test tests/Febe.Tests.Windows, WebView2 vero: solo su Windows), prove con filtro (chiede il filtro, per esempio FullyQualifiedName~Febe.Tests.Docs), sito di prova, pubblica Febe.exe (un file solo in out/pubblicazione/, come installer/costruisci.sh) e immagine Docker (serve Docker Desktop).
  • I file di .vscode/ sono JSON senza commenti, così li legge anche un lettore rigido come quello dei controlli della CI: le spiegazioni stanno in questa sezione, nei campi detail delle attività e in docs/decisioni.md.

Dimostrazione

dotnet run --project src/Febe.Server -- --demo [--porta 8480] [--fuso Europe/Rome]

Parte senza browser e senza rete, solo su 127.0.0.1 e senza password, con una libreria temporanea di account finti (.demo), immagini generate e un motore finto; la cartella si cancella alla chiusura. Non scrive mai nella libreria vera e non invia messaggi Telegram.

  • Scene: ?scena=normale, sessione, fermo, scollegato, errore; tema ?tema=chiaro o scuro; veste ?veste=desktop o docker.
  • Indirizzi diretti: /account?dialogo=aggiungi, /account/3/impostazioni, /importa?passo=3, /doppioni.
  • Per modificare l'interfaccia senza ricompilare: FEBE_INTERFACCIA=$PWD/src/Febe.Web/wwwroot dotnet run --project src/Febe.Server -- --demo, poi basta ricaricare.

Simulazione

dotnet run --project src/Febe.Server -- --simula 30g --profilo prudente [--csv resoconto.csv] [--seme 7]

Fa girare il motore vero con l'orologio virtuale contro un mondo finto (40 account, 25 seguiti, uno con uno storico di 2.000 post, qualche rallentamento a caso) e scrive il resoconto: sessioni al giorno, azioni per categoria al giorno e nell'ora peggiore, tempo medio e massimo fra pubblicazione e scoperta, giorni per lo storico, superamenti dei tetti (devono essere zero). Profili: prudente, equilibrato, rapido. È il modo per giudicare un profilo prima di usarlo.

Il sito di prova

dotnet run --project tools/Febe.SitoDiProva -- --porta 8481 --porta-cdn 8482

Un sito locale con pagine spoglie e dati sintetici (alberto.prova, marta.prova, …): pagina iniziale con barra delle storie, profili con griglia che carica scorrendo, visualizzatore delle storie e delle raccolte, elenco dei seguiti, post singoli, e i casi di arresto. Non somiglia a Instagram e non ha pagine di accesso. I casi di arresto si comandano da fuori: /_controllo/modo?valore=troppe-richieste|verifica|sessione-scaduta|vuoto|formato-sconosciuto|normale. Dettagli in tools/Febe.SitoDiProva/LEGGIMI.md.

Il server vero contro il sito di prova (mai Instagram):

FEBE_PASSWORD=prova dotnet run --project src/Febe.Server -- \
  --dati /tmp/febe/dati --libreria /tmp/febe/libreria --importa /tmp/febe/importa --ascolta 127.0.0.1 \
  --sito-di-prova http://127.0.0.1:8481 --accesso-di-prova --prima-sessione 5

--sito-di-prova accetta solo indirizzi di questo computer; --accesso-di-prova apre il sito una volta all'avvio, così il suo cookie di sessione esiste come dopo un accesso; --prima-sessione N fa partire la prima sessione dopo N secondi. Come root servono --senza-sandbox e, se Chromium non è nel PATH, FEBE_CHROMIUM. Per provare gli avvisi: imposta Telegram in Impostazioni ▸ Notifiche e chiedi al sito una verifica con /_controllo/modo?valore=verifica.

La sonda

febe-sonda registra --cartella <fuori dal repository> [--display :0 | --xvfb] [--chromium <file>]
febe-sonda ripulisci --da <grezzi> --a <ripuliti>
febe-sonda verifica --grezzi <grezzi> --ripuliti <ripuliti>

(oppure dotnet run --project tools/Febe.Sonda -- …). È passiva: apre il browser e registra ciò che la pagina riceve mentre navighi tu; non compie gesti. I campioni grezzi stanno fuori dal repository, contengono dati di altre persone e si cancellano dopo l'uso; nel repository entrano solo i campioni ripuliti. La procedura completa è la parte A di docs/prove-dal-vivo.md; vedi anche Ipotesi da verificare.

Schermate

bash tools/schermate/tutte.sh 8490 rifà le schermate di docs/schermate/ da una dimostrazione avviata su quella porta, per il confronto con i mockup (§10.7 della specifica); le differenze rimaste sono in docs/schermate/differenze.md. Lo strumento accetta solo indirizzi di questo computer.

Immagine Docker

docker build -f docker/Dockerfile -t febe .

La compilazione e tutte le prove girano dentro la costruzione dell'immagine (quelle con il browser vero lì si saltano da sole). Vedi Installazione con Docker e Unraid e docs/docker.md.

CI e rilascio

Il repository è sul Gitea di casa (https://gitea.encke-hake.ts.net/Alby96/Febe); la CI usa Gitea Actions in .gitea/workflows/, con il codice comune in .gitea/scripts/. Il processo completo (nomi dei rami, commit, richieste di unione, protezione di main, rilievi di sicurezza, rilasci, correzioni urgenti) è in docs/processo.md.

  • verifica.yml, a ogni push su qualunque ramo e a mano (non sui tag, non sulle richieste di unione, che mostrano lo stato del loro ultimo commit). Quattro lavori, che sono i controlli richiesti per unire in main:
    • controlli: sintassi degli script, file di testo, versione, progetti della soluzione, JSON, e nessun segreto in tutta la storia (gitleaks);
    • prove: compilazione di tutta la soluzione con gli avvisi come errori e tutte le prove di tests/Febe.Tests in un contenitore Debian con Chromium, Xvfb, ffmpeg, NSIS e Node veri: nessuna prova si salta;
    • installatore: Febe-Setup-<versione>-ci.<numero>.exe e lo zip portabile, fra gli artefatti per 14 giorni;
    • immagine, dopo l'installatore: l'immagine Docker, provata senza rete (parte, diventa «healthy», si ferma) e scansionata con Trivy; dopo un push su main va sul registro come :main e :sha-<commit>. Alla fine si toglie tutto ciò che l'esecuzione ha creato sul demone Docker, che è condiviso con gli altri progetti, e poi, di tutti, le immagini senza nome e la cache di costruzione che nessuno usa da 24 ore;
  • rilascio.yml, a ogni tag vX.Y.Z: prove, installatore e zip, immagine provata e scansionata, pubblicata come :X.Y.Z e :latest (solo per le versioni senza trattino), poi la release;
  • pulizia.yml, ogni lunedì e a mano: i resti delle esecuzioni interrotte e dei lavori di act_runner, le immagini che nessun contenitore usa e la cache di costruzione più vecchie di 24 ore, di tutti i progetti, e sul registro le :sha- oltre le 10 più recenti; mai un contenitore, un volume o una rete che non sia della CI. A mano, con «Solo prova», elenca che cosa toglierebbe e non toglie nulla (docs/processo.md, «Pulizia»).

Nella CI le prove del sito di prova (categoria SitoDiProva) girano due volte: con il seme 13 e con un seme diverso a ogni esecuzione, scritto nel registro del lavoro. Per rifare un errore con quel seme: FEBE_SEME_PROVA=<seme> dotnet test tests/Febe.Tests --filter "TestCategory=SitoDiProva". I controlli veloci della CI si lanciano anche a mano: bash .gitea/scripts/controlli.sh.

La versione sta solo in Directory.Build.props (<Version>); il tag deve coincidere.

La guida

Le pagine di questa guida sono i file di docs/guida/, una pagina del wiki per file (_Sidebar.md è la navigazione). Il wiki di Gitea è un repository git a parte: per pubblicarla si copiano i file in https://gitea.encke-hake.ts.net/Alby96/Febe.wiki.git e si fa push. I collegamenti fra le pagine sono nel formato del wiki, [Testo](Nome-Pagina), senza .md.

Convenzioni

  • Codice e commenti in inglese; interfaccia, documenti e messaggi in italiano (glossario: appendice D della specifica).
  • Nel motore mai DateTime.Now, Task.Delay o Random diretti: si usano IClock e IRandomSource.
  • Mai password, cookie, tasti, gettoni o corpi di risposta nei registri; il client DevTools registra solo i nomi dei comandi. Gli indirizzi verso Telegram contengono il gettone del bot: non si registrano mai.
  • La libreria non cancella e non sostituisce file da sola.
  • Una scelta tecnica nuova si scrive in docs/decisioni.md con data e motivo.