Protocolli interni · 0.1.0
Confini dei servizi interni
I protocolli di scanner, updater e connettore Advisor sono documentati separatamente dall’API di controllo.
Il riferimento API è in inglese.
Questi protocolli collegano componenti interni del workbench. Sono interfacce d’implementazione, non endpoint supportati per integrazioni esterne. Usa l’API di controllo con l’autorità client supportata per i flussi applicativi.
Assegna a ogni servizio una responsabilità ristretta
Coordinatore
- Worker dei job
Gestisce l’operazione persistente e i legami esatti con i servizi.
Protocolli separati
- Protocollo scanner
Esecuzioni limitate, rilievi paginati e conferma esplicita del risultato.
- Protocollo updater
Preparazione e riconciliazione di componenti verificati senza accesso ai sorgenti di progetto.
- Protocollo connettore Advisor
Lavoro legato a concessioni, destinazioni e stato d’annullamento esatti.
Connessioni
Worker dei job a Protocollo scanner
Raccogli e persisti il risultato esatto prima di confermare la pulizia.
Worker dei job a Protocollo updater
Segui identità e digest della richiesta durante preparazione e recupero.
Worker dei job a Protocollo connettore Advisor
Emetti solo l’autorità del provider necessaria per la richiesta prevista.
| Servizio | Chiamante e risorse | Responsabilità del protocollo |
|---|---|---|
| Scanner | Worker; sorgenti autorizzati, snapshot e cache validata in sola lettura | Ammissione delle esecuzioni, stato, rilievi limitati, conferma del risultato esatto e annullamento. |
| Updater dei dati | API/worker; cache scrivibile ed egress di download verificati | Preparazione persistente e pubblicazione di generazioni complete, senza accesso ai sorgenti dei progetti. |
| Connettore Advisor | Worker; autorizzazione dedicata e percorsi di rete approvati | Test provider, generazione, osservazione e annullamento con concessioni ristrette. |
Il nucleo pubblica solo il relay d’ingresso loopback. Questi servizi non sono endpoint del sito pubblico. Rete interna dello scanner ed egress di updater e Advisor sono distinti in Compose. Mount e reti dichiarati richiedono verifica in immagini e container prima di essere considerati isolamento osservato.
Scanner runtime
Il worker avvia un’esecuzione stabile con POST /runs, ne osserva lo stato e legge pagine limitate di rilievi. Identità e digest della richiesta impediscono di sostituire un altro comando sotto l’esecuzione esistente. Il manifest sigillato aggiunge digest del risultato, conteggi, identità dello stream, riepilogo e dichiarazioni degli artefatti.
I cursori legano esecuzione, richiesta, risultato e posizione esatti. Il worker valida tutto lo stream prima della pubblicazione nel database. POST /runs/{run_id}/result/ack libera il risultato temporaneo esatto dopo la persistenza. Annullamento e pulizia con DELETE /runs/{run_id} devono conservare il legame corretto di richiesta e risultato; non sono comandi arbitrari di eliminazione file.
Registro delle esecuzioni e spool di recupero sono locali al processo e limitati nel tempo. Riavviare lo scanner non conserva lo spool come evidenza persistente. La risposta di salute non stabilisce nemmeno che binari, regole e database siano pronti. Consulta route, controllo delle esecuzioni e commit prima dell’ACK.
Updater senza accesso ai sorgenti
Riceve operazioni persistenti legate a UUID e digest della richiesta. L’esecutore recupera lo stato e gestisce lavoro attivo e pendente limitato. Gli handler risolvono componenti verificati, preparano candidati privati, li validano e sigillano, poi pubblicano una generazione completa. Non accettano percorsi di repository, URL di download o comandi shell arbitrari al posto del catalogo verificato.
Il confine HTTP privato richiede un Host consentito e rifiuta header di host o protocollo inoltrati. È una barriera aggiuntiva, non una ragione per esporlo pubblicamente. L’updater non monta sorgenti di progetto; lo scanner consuma la cache validata in sola lettura.
Attivazione e annullamento hanno esiti distinti. Quando la pubblicazione entra nel commit protetto, annullare non può interromperla o invertire la selezione. Il rollback è un’altra operazione validata e richiede dati precedenti compatibili e validi. Consulta avvio e confine delle richieste, route operative e architettura della preparazione.
Connettore Advisor
Il lavoro locale e remoto passa dal connettore. Il worker riserva o ammette un’operazione limitata, presenta la concessione richiesta e chiede generazione. Il connettore verifica percorso provider e modello autorizzati, poi valida la risposta. Ha materiale d’autorizzazione dedicato e nessun sorgente montato; il worker fornisce il pacchetto ammesso del rilievo.
La generazione remota richiede il percorso per un singolo rilievo confermato separatamente. La conferma lega configurazione, autorità, trasporto, destinazione, identità del modello, revisione e hash del prompt. La selezione automatica e sull’intera scansione resta solo locale. Il trasporto remoto supporta percorsi Ollama diretti o SSH verificati, non provider arbitrari.
Ammissione, osservazione e annullamento sono endpoint espliciti. Annullare può fermare lavoro successivo ma non richiamare contenuti inviati. Il worker rivalida i consigli e li scarta se il rilievo cambia durante la generazione. Non modifica automaticamente ciclo di vita o policy del gate.
Consulta operazioni e generazione del connettore, integrazione worker e legame della divulgazione.
Leggi il protocollo insieme all’implementazione
Il riferimento interno descrive dichiarazioni nello snapshot API identificato. Alcuni handler leggono e validano JSON direttamente; uno schema ampio generato non esprime tutte le chiavi, i legami o le condizioni d’autorità. Leggi handler e chiamante insieme quando cambi un protocollo.
Gli schemi da soli non provano avvio, raggiungibilità, autorizzazione provider, recupero o supporto d’integrazione. Cambiare protocolli richiede validazione coordinata tra servizio e chiamante e prove di rifiuto e recupero. Le integrazioni pubbliche non devono dipendere dalla stabilità di questi endpoint.