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>
16 KiB
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.Desktopsi compila anche da Linux (EnableWindowsTargeting), ma gira solo su Windows. - Le prove con un browser vero cercano Chromium in
FEBE_CHROMIUM(o nelPATH) e Xvfb nelPATH; 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.Docscontrolla 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>\datie%USERPROFILE%\FebeSviluppo\<checkout>\libreria, dove<checkout>è il nome della cartella aperta in VS Code (per esempioFebe; 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,
compilanon può sovrascrivereFebe.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 dilaunchSettings.json, inFebeSviluppo\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
dotnetnon trova l'SDK 10 o Febe non parte («You must install or update .NET»). Se nel terminaledotnet --list-sdksnon mostra il 10, usa le attività, Git Bash oppureconda 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. Condotnet run --project src/Febe.Server -- --demoin 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 disrc/Febe.Desktop/Properties/launchSettings.json: sito di prova suhttp://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 condotnet 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 esempioFullyQualifiedName~Febe.Tests.Docs),sito di prova,pubblica Febe.exe(un file solo inout/pubblicazione/, comeinstaller/costruisci.sh) eimmagine 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 campidetaildelle attività e indocs/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=chiarooscuro; veste?veste=desktopodocker. - 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 inmain: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 ditests/Febe.Testsin un contenitore Debian con Chromium, Xvfb, ffmpeg, NSIS e Node veri: nessuna prova si salta;installatore:Febe-Setup-<versione>-ci.<numero>.exee 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 sumainva sul registro come:maine: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 tagvX.Y.Z: prove, installatore e zip, immagine provata e scansionata, pubblicata come:X.Y.Ze: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.DelayoRandomdiretti: si usanoIClockeIRandomSource. - 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.mdcon data e motivo.