Ecosistema e catalogo dei plugin WebBlocks

Questo documento registra la direzione dell'ecosistema di plugin WebBlocks per la fase successiva, prima che inizi l'implementazione. È solo documentazione di architettura. Non aggiunge codice runtime, rotte, migrazioni, controller, client API, tabelle di database, schermate di amministrazione, automazione di deploy, tag di release o incrementi di versione.

L'architettura dei plugin WebBlocks dovrebbe riguardare l'intero ecosistema, non solo il CMS. WebBlocks CMS è il primo host di plugin perché dispone già delle fondamenta del sistema di plugin: definizioni basate su un registro, caricamento e installazione manuale di ZIP, plugin installati disattivati per impostazione predefinita, controlli di compatibilità e comportamento inerte quando sono disattivati o incompatibili. Lo stesso contratto dovrebbe essere riutilizzabile da altri prodotti WebBlocks quando servono estensioni basate su pacchetti con una proprietà chiara e regole di ciclo di vita sicure.

Progettare il contratto solo attorno al CMS renderebbe più difficile condividere in seguito l'identità dei plugin, il packaging, la compatibilità, i metadati del catalogo e le regole di sicurezza. La direzione obiettivo è un contratto di plugin WebBlocks condiviso che ogni prodotto possa ospitare tramite i propri punti di estensione, preservando un modello comune per identità, ispezione dei pacchetti, compatibilità, abilitazione, aggiornamenti e scoperta nel catalogo.

I possibili host di plugin includono:

• WebBlocks CMS
• QuizTem
• Herne Panel
• WebBlocks Publisher
• futuri prodotti WebBlocks

Ogni prodotto host può esporre punti di estensione diversi. WebBlocks CMS espone menu di amministrazione del CMS, rotte di plugin, permessi, impostazioni, comandi, migrazioni, blocchi, asset, health check, widget della dashboard e schede di sistema. QuizTem, Herne Panel, WebBlocks Publisher e i prodotti futuri possono esporre registri e schermate propri diversi.

Anche quando i punti di estensione differiscono, l'identità dei plugin, il packaging, la compatibilità, il ciclo di vita e i metadati del catalogo dovrebbero seguire convenzioni condivise in tutto l'ecosistema WebBlocks. Un plugin può supportare un solo prodotto host o più prodotti host, ma la compatibilità di prodotto deve essere sempre esplicita e ispezionabile prima dell'abilitazione.

Ogni plugin dell'ecosistema dovrebbe avere un handle stabile:

• in kebab-case
• globalmente univoco nell'intero ecosistema WebBlocks
• stabile tra le release
• usato come prefisso predefinito per rotte, permessi, impostazioni, comandi, tabelle, asset e identità del pacchetto

La proprietà basata sul prefisso dell'handle mantiene il comportamento del plugin attribuibile e al riparo dalle collisioni. Rotte di amministrazione, rotte pubbliche, stringhe di permesso, namespace delle impostazioni, nomi dei comandi, prefissi delle tabelle di database, handle degli asset, nomi dei pacchetti, percorsi degli artefatti e record del catalogo dovrebbero essere tutti riconducibili all'handle del plugin proprietario.

La compatibilità di prodotto deve essere esplicita. Un plugin può supportare solo WebBlocks CMS, solo QuizTem, solo Herne Panel, solo WebBlocks Publisher oppure una combinazione supportata di prodotti host. I prodotti host non supportati devono trattare il plugin come incompatibile e inerte.

L'ecosistema dovrebbe muoversi verso un concetto di manifest condiviso, ispezionabile prima dell'installazione e prima dell'abilitazione. L'API concreta di implementazione può evolvere e i prodotti host possono adattare il manifest a registri specifici del prodotto, ma proprietà e compatibilità devono restare ispezionabili prima dell'abilitazione.

I metadati del futuro manifest condiviso dovrebbero includere:

• handle
• label
• vendor o author
• version
• i prodotti host supportati
• le versioni richieste del prodotto host
• le versioni di PHP e Laravel richieste, quando applicabile
• le classi provider per prodotto host, quando necessario
• i permessi
• i contributi al menu di amministrazione
• le dichiarazioni delle rotte
• i comandi
• le migrazioni
• i blocchi o i pacchetti di blocchi
• gli asset
• le impostazioni
• gli health check
• le note di rilascio
• i metadati di checksum e firma

Il manifest dovrebbe permettere a un host di rispondere a domande di sicurezza prima di abilitare del codice: quali prodotti supporta il pacchetto, quali versioni di prodotto sono richieste, quali provider possono avviarsi, quali rotte e comandi verrebbero registrati, quali permessi verrebbero creati, quali tabelle e namespace di impostazioni gli appartengono, quali migrazioni possono essere proposte per una configurazione esplicita e quali artefatti possono essere verificati.

plugins.webblocksui.com è la superficie di catalogo/store proposta per il futuro. Questo documento non implica che il dominio esista, sia distribuito o sia attivo.

I termini dovrebbero restare distinti:

• Plugin Catalog: scoperta, metadati, compatibilità, documentazione, screenshot, link di supporto, metadati di rilascio, stato di sicurezza e link di download.
• Plugin Store: successiva integrazione di installazione/aggiornamento da metadati di catalogo attendibili verso un prodotto host.
• Marketplace: future funzionalità commerciali quali account, licenze, plugin a pagamento, recensioni, flussi di approvazione, profili degli editori e flussi di ricavi.

Il primo traguardo dovrebbe essere un Plugin Catalog, non un Marketplace commerciale completo. Un catalogo può stabilire il contratto dei metadati, la matrice di compatibilità, i checksum degli artefatti, i link alla documentazione e un percorso di download manuale sicuro senza aggiungere installazione remota, aggiornamenti automatici, licenze a pagamento o flussi di approvazione commerciale.

Per il posizionamento del prodotto, l'ambito dell'MVP, i modelli di implementazione candidati, le superfici del sito web pubblico, i concetti di operatore e la pianificazione dell'API del prodotto di catalogo proposto, vedete Plugin Catalog Product Architecture.

1. Fase 1: documentazione e contratto dei metadati.
2. Fase 2: pianificazione del server e del modello dati del catalogo per plugins.webblocksui.com.
3. Fase 3: interfaccia di sola lettura Browse Plugin Catalog nell'amministrazione del CMS. Implementata come /webadmin/plugins/catalog, usando WEBBLOCKS_PLUGIN_CATALOG_BASE_URL / webblocks-plugins.catalog.base_url e con https://plugins.webblocksui.com come valore predefinito.
4. Fase 4: flusso di download/installazione manuale dello ZIP collegato dai metadati del catalogo.
5. Fase 5: flusso controllato Install from Catalog, comunque disattivato per impostazione predefinita dopo l'installazione.
6. Fase 6: controllo e disponibilità degli aggiornamenti dei plugin. Implementato per System -> Plugins -> Registered Plugins del CMS quando gli handle dei plugin installati hanno release di catalogo più recenti e compatibili con metadati di artefatto completi.
7. Fase 7: flusso controllato di applicazione degli aggiornamenti dei plugin. Implementato come azione POST da super-admin che riutilizza la verifica del checksum del catalogo e la validazione dello ZIP del plugin, preservando lo stato del ciclo di vita e lasciando esplicite le migrazioni.
8. Fase 8: funzionalità di marketplace, licenze e commerciali.

Ogni fase deve preservare l'installazione disattivata per impostazione predefinita, il comportamento che mette la compatibilità al primo posto e le azioni esplicite di configurazione o migrazione. I metadati remoti possono aiutare a scoprire, valutare, installare o aggiornare esplicitamente i plugin, ma non devono abilitare plugin in silenzio, eseguire migrazioni, applicare aggiornamenti o aggirare le regole di compatibilità del prodotto host.

Il browser del catalogo del CMS elenca i plugin pubblici del catalogo compatibili con WebBlocks CMS e i metadati dell'ultima release compatibile. Il CMS dispone ora di azioni esplicite di installazione/aggiornamento dal catalogo riservate al super-admin per artefatti ZIP attendibili con metadati di checksum completi, ma la sola navigazione del catalogo non installa pacchetti Composer, non abilita plugin, non esegue migrazioni, non registra rotte, comandi, provider o permessi e non attiva lo stato di un plugin a partire da dati remoti.

L'indisponibilità del catalogo o dello store non deve compromettere la gestione dei plugin installati. L'elenco dei plugin installati, i controlli di abilitazione/disabilitazione, le indicazioni di configurazione, lo stato di salute e la disinstallazione devono continuare a funzionare a partire dallo stato locale.

I dati remoti del catalogo non devono abilitare automaticamente i plugin. I dati remoti del catalogo non devono eseguire automaticamente migrazioni. I dati remoti del catalogo non devono applicare automaticamente aggiornamenti. Gli aggiornamenti basati sul catalogo richiedono un'azione POST esplicita da super-admin e metadati di artefatto attendibili. L'installazione automatica e arbitraria tramite Composer è fuori ambito, a meno che una futura decisione di architettura non la approvi esplicitamente.

Gli artefatti ZIP devono essere verificati prima dell'installazione. La verifica dovrebbe bloccare il path traversal, i file di metadati nascosti, l'uscita dalla radice, gli eseguibili a sorpresa in area pubblica, le collisioni di rotte, le collisioni di permessi, le collisioni di prefissi di tabella, le collisioni dei confini tra prodotti host, le fughe tramite symlink, le destinazioni di installazione vietate, i manifest malformati, i prodotti host incompatibili e le discrepanze di checksum o di future firme.

I plugin incompatibili, disattivati, con file mancanti o insicuri devono restare inerti. Non devono registrare rotte, comandi, menu, permessi, rotte di impostazioni, migrazioni, job pianificati, blocchi, asset, widget, reporter di stato né altro comportamento attivo a runtime.

La disinstallazione resta «prima disattivare» e di competenza dello storage. Una disinstallazione ordinaria deve rimuovere solo la directory del pacchetto del plugin che risiede nello storage e i record locali dello stato di abilitazione. Non deve eliminare le tabelle di database di proprietà del plugin, a meno che in futuro non venga progettato intenzionalmente uno strumento di pulizia distruttiva con conferma esplicita.

La sovrascrittura delle viste del core resta vietata per impostazione predefinita. L'estensione tramite plugin deve usare i registri documentati o gli slot di estensione. I plugin non devono sostituire le viste del pacchetto, applicare monkey patch ai servizi del prodotto, aggiungere file di rotte nascosti o affidarsi a effetti collaterali arbitrari di un include.

I record del Plugin Catalog dovrebbero includere:

• metadati della scheda del plugin: handle, etichetta, descrizione, fornitore/autore, categorie, tag, release stabile corrente, URL della documentazione, screenshot, URL di supporto e URL del codice sorgente o del tracker delle issue quando disponibili
• metadati di rilascio: versione, data di rilascio, note di rilascio, URL degli artefatti, checksum, firme future, requisiti minimi dell'host, note di aggiornamento e stato di deprecazione
• metadati di compatibilità: prodotti host supportati, vincoli di versione supportati del prodotto host, versioni di PHP/Laravel richieste quando applicabile, servizi di piattaforma supportati e requisiti di migrazione/configurazione
• metadati di avviso di sicurezza e deprecazione: versioni interessate, versioni corrette, gravità, link agli avvisi, flag di insicurezza, release deprecate, indicazioni sulla sostituzione e stato di blocco dell'installazione/aggiornamento
• metadati di verifica degli artefatti: algoritmo di checksum, valore del checksum, dimensione dell'artefatto, dati di firma futuri, identità della chiave di firma e stato di integrità
• URL di documentazione, screenshot e supporto: documentazione pubblica, changelog, guida alla configurazione, screenshot, contatto di supporto, tracker delle issue e profilo del fornitore
• matrice di compatibilità dei prodotti host: una riga per ogni prodotto host supportato, con handle del prodotto, etichetta del prodotto, vincoli di versione compatibili, metadati della classe provider quando necessari, punti di estensione usati, requisiti di configurazione e limitazioni note

I metadati del catalogo dovrebbero essere utili prima del download, prima dell'installazione, prima dell'abilitazione, prima della configurazione/migrazione e prima dell'applicazione di un aggiornamento.

Il futuro Plugin Catalog può riutilizzare idee dell'attuale flusso di metadati di aggiornamento di WebBlocks Publisher, inclusi metadati di rilascio, checksum degli artefatti, manifest e concetti di distribuzione ospitata. La pubblicazione nel catalogo dei plugin dovrebbe comunque essere documentata come capacità di prodotto separata.

Questo documento non presuppone un'implementazione all'interno del codice attuale di WebBlocks Publisher. plugins.webblocksui.com potrà in seguito essere alimentato da WebBlocks Publisher, da un'applicazione di catalogo dedicata o da un sito WebBlocks CMS con un plugin di catalogo. La scelta implementativa dovrebbe essere fatta dopo che il contratto dei metadati del catalogo e il confine di prodotto saranno chiari.

Vedete Plugin System per l'attuale architettura dell'host di plugin di WebBlocks CMS.

Il caricamento e l'installazione manuale dello ZIP nel CMS restano l'attuale metodo di installazione dei plugin supportato. I plugin caricati vengono installati in percorsi dello storage, restano disattivati per impostazione predefinita e richiedono azioni esplicite di abilitazione e di configurazione/migrazione. I plugin disattivati e incompatibili restano inerti.

Il lavoro su catalogo/store dovrebbe basarsi sul ciclo di vita dei plugin già esistente nel CMS invece di sostituirlo. La futura scoperta nel catalogo, i link di download manuale, i flussi di installazione dal catalogo, i controlli degli aggiornamenti e le azioni controllate di applicazione degli aggiornamenti dovrebbero riutilizzare le stesse regole di handle, compatibilità, disattivazione predefinita, configurazione richiesta, prontezza dello schema, permessi, proprietà delle rotte e sicurezza della disinstallazione.

Questa fase non include:

• l'implementazione a runtime
• l'installazione remota automatica
• l'applicazione automatica degli aggiornamenti dei plugin
• il comportamento di marketplace a pagamento
• il comportamento di un server di licenze
• il flusso di approvazione di terze parti
• l'automazione del deploy in produzione
• la verifica sul sito in produzione