Écosystème et catalogue de plugins WebBlocks

Ce document consigne l'orientation de l'écosystème de plugins WebBlocks pour l'étape suivante, avant le début de l'implémentation. Il s'agit uniquement de documentation d'architecture. Il n'ajoute ni code d'exécution, ni routes, ni migrations, ni contrôleurs, ni clients d'API, ni tables de base de données, ni écrans d'administration, ni automatisation de déploiement, ni tags de version, ni incréments de version.

L'architecture de plugins WebBlocks devrait couvrir tout l'écosystème, et pas seulement le CMS. WebBlocks CMS est le premier hôte de plugins car il dispose déjà des fondations du système de plugins : définitions adossées à un registre, téléversement et installation manuelle de ZIP, plugins installés désactivés par défaut, contrôles de compatibilité et comportement inerte lorsqu'ils sont désactivés ou incompatibles. Le même contrat devrait être réutilisable par les autres produits WebBlocks lorsqu'ils ont besoin d'extensions livrées en paquets, avec une propriété claire et des règles de cycle de vie sûres.

Concevoir le contrat uniquement autour du CMS rendrait plus difficile le partage ultérieur de l'identité des plugins, de l'empaquetage, de la compatibilité, des métadonnées de catalogue et des règles de sécurité. L'orientation visée est un contrat de plugins WebBlocks partagé que chaque produit peut héberger via ses propres points d'extension, tout en préservant un modèle commun pour l'identité, l'inspection des paquets, la compatibilité, l'activation, les mises à jour et la découverte au catalogue.

Les hôtes de plugins possibles sont :

• WebBlocks CMS
• QuizTem
• Herne Panel
• WebBlocks Publisher
• futurs produits WebBlocks

Chaque produit hôte peut exposer des points d'extension différents. WebBlocks CMS expose des menus d'administration du CMS, des routes de plugin, des permissions, des réglages, des commandes, des migrations, des blocs, des ressources, des contrôles de santé, des widgets de tableau de bord et des cartes système. QuizTem, Herne Panel, WebBlocks Publisher et les futurs produits peuvent exposer d'autres registres et écrans qui leur sont propres.

Même lorsque les points d'extension diffèrent, l'identité des plugins, l'empaquetage, la compatibilité, le cycle de vie et les métadonnées de catalogue devraient suivre des conventions partagées dans tout l'écosystème WebBlocks. Un plugin peut prendre en charge un seul produit hôte ou plusieurs, mais la compatibilité produit doit toujours être explicite et inspectable avant l'activation.

Tout plugin de l'écosystème devrait posséder un handle stable :

• en kebab-case
• globalement unique dans tout l'écosystème WebBlocks
• stable d'une version à l'autre
• utilisé comme préfixe par défaut pour les routes, permissions, réglages, commandes, tables, ressources et l'identité du paquet

La propriété fondée sur le préfixe du handle garde le comportement du plugin attribuable et à l'abri des collisions. Les routes d'administration, les routes publiques, les chaînes de permission, les espaces de noms de réglages, les noms de commandes, les préfixes de tables de base de données, les handles de ressources, les noms de paquets, les chemins d'artefacts et les enregistrements du catalogue devraient tous être traçables jusqu'au handle du plugin propriétaire.

La compatibilité produit doit être explicite. Un plugin peut prendre en charge uniquement WebBlocks CMS, uniquement QuizTem, uniquement Herne Panel, uniquement WebBlocks Publisher, ou une combinaison prise en charge de produits hôtes. Les produits hôtes non pris en charge doivent traiter le plugin comme incompatible et inerte.

L'écosystème devrait s'orienter vers une notion de manifeste partagé, inspectable avant l'installation et avant l'activation. L'API d'implémentation exacte peut évoluer, et les produits hôtes peuvent adapter le manifeste à des registres propres au produit, mais la propriété et la compatibilité doivent rester inspectables avant l'activation.

Les métadonnées du futur manifeste partagé devraient inclure :

• handle
• label
• vendor ou author
• version
• les produits hôtes pris en charge
• les versions requises du produit hôte
• les versions de PHP et Laravel requises, le cas échéant
• les classes de fournisseur par produit hôte, lorsque nécessaire
• les permissions
• les contributions au menu d'administration
• les déclarations de routes
• les commandes
• les migrations
• les blocs ou packs de blocs
• les ressources
• les réglages
• les contrôles de santé
• les notes de version
• les métadonnées de somme de contrôle et de signature

Le manifeste devrait permettre à un hôte de répondre aux questions de sûreté avant d'activer du code : quels produits le paquet prend en charge, quelles versions de produit sont requises, quels fournisseurs peuvent démarrer, quelles routes et commandes seraient enregistrées, quelles permissions seraient créées, quelles tables et quels espaces de noms de réglages lui appartiennent, quelles migrations peuvent être proposées pour une configuration explicite, et quels artefacts peuvent être vérifiés.

plugins.webblocksui.com est la surface de catalogue/boutique proposée pour l'avenir. Ce document n'implique pas que le domaine existe, soit déployé ou soit en ligne.

Les termes doivent rester distincts :

• Plugin Catalog : découverte, métadonnées, compatibilité, documentation, captures d'écran, liens de support, métadonnées de version, état de sécurité et liens de téléchargement.
• Plugin Store : intégration ultérieure d'installation/mise à jour depuis des métadonnées de catalogue de confiance vers un produit hôte.
• Marketplace : futures fonctionnalités commerciales telles que comptes, licences, plugins payants, avis, flux d'approbation, profils d'éditeurs et flux de revenus.

Le premier jalon devrait être un Plugin Catalog, et non un Marketplace commercial complet. Un catalogue peut établir le contrat de métadonnées, la matrice de compatibilité, les sommes de contrôle des artefacts, les liens de documentation et un chemin de téléchargement manuel sûr, sans ajouter d'installation distante, de mises à jour automatiques, de licences payantes ni de flux d'approbation commerciale.

Pour le positionnement produit, le périmètre du MVP, les modèles d'implémentation candidats, les surfaces du site web public, les concepts d'opérateur et la planification de l'API du produit de catalogue proposé, voir Plugin Catalog Product Architecture.

1. Phase 1 : documentation et contrat de métadonnées.
2. Phase 2 : planification du serveur et du modèle de données du catalogue pour plugins.webblocksui.com.
3. Phase 3 : interface en lecture seule Browse Plugin Catalog dans l'administration du CMS. Implémentée sous /webadmin/plugins/catalog, utilisant WEBBLOCKS_PLUGIN_CATALOG_BASE_URL / webblocks-plugins.catalog.base_url et pointant par défaut sur https://plugins.webblocksui.com.
4. Phase 4 : flux de téléchargement/installation manuelle du ZIP, lié depuis les métadonnées du catalogue.
5. Phase 5 : flux contrôlé Install from Catalog, toujours désactivé par défaut après l'installation.
6. Phase 6 : vérification et disponibilité des mises à jour de plugins. Implémentée pour System -> Plugins -> Registered Plugins du CMS lorsque les handles de plugins installés disposent de versions de catalogue plus récentes et compatibles, avec des métadonnées d'artefact complètes.
7. Phase 7 : flux contrôlé d'application des mises à jour de plugins. Implémenté comme une action POST réservée au super-admin qui réutilise la vérification de somme de contrôle du catalogue et la validation du ZIP du plugin, tout en préservant l'état du cycle de vie et en laissant les migrations explicites.
8. Phase 8 : fonctionnalités de marketplace, de licence et commerciales.

Chaque phase doit préserver l'installation désactivée par défaut, le comportement donnant la priorité à la compatibilité et les actions explicites de configuration ou de migration. Les métadonnées distantes peuvent aider à découvrir, évaluer, installer ou mettre à jour explicitement des plugins, mais elles ne doivent pas activer de plugins en silence, exécuter des migrations, appliquer des mises à jour ni contourner les règles de compatibilité du produit hôte.

Le navigateur de catalogue du CMS liste les plugins publics du catalogue compatibles avec WebBlocks CMS ainsi que les métadonnées de la dernière version compatible. Le CMS dispose désormais d'actions explicites d'installation/mise à jour depuis le catalogue, réservées au super-admin, pour des artefacts ZIP de confiance dotés de métadonnées de somme de contrôle complètes ; mais la simple navigation dans le catalogue n'installe pas de paquets Composer, n'active pas de plugins, n'exécute pas de migrations, n'enregistre ni routes, ni commandes, ni fournisseurs, ni permissions, et n'active aucun état de plugin à partir de données distantes.

L'indisponibilité du catalogue ou de la boutique ne doit pas casser la gestion des plugins installés. La liste des plugins installés, les contrôles d'activation/désactivation, les indications de configuration, l'état de santé et la désinstallation doivent continuer de fonctionner à partir de l'état local.

Les données distantes du catalogue ne doivent pas activer automatiquement de plugins. Les données distantes du catalogue ne doivent pas exécuter automatiquement de migrations. Les données distantes du catalogue ne doivent pas appliquer automatiquement de mises à jour. Les mises à jour issues du catalogue exigent une action POST explicite du super-admin et des métadonnées d'artefact de confiance. L'installation automatique et arbitraire via Composer est hors périmètre, sauf si une future décision d'architecture l'approuve explicitement.

Les artefacts ZIP doivent être vérifiés avant l'installation. La vérification devrait bloquer la traversée de chemin, les fichiers de métadonnées cachés, l'échappement hors de la racine, les exécutables surprises en zone publique, les collisions de routes, les collisions de permissions, les collisions de préfixes de tables, les collisions de frontières entre produits hôtes, les échappements par lien symbolique, les cibles d'installation interdites, les manifestes mal formés, les produits hôtes incompatibles et les non-concordances de somme de contrôle ou de future signature.

Les plugins incompatibles, désactivés, aux fichiers manquants ou non sûrs doivent rester inertes. Ils ne doivent enregistrer ni routes, ni commandes, ni menus, ni permissions, ni routes de réglages, ni migrations, ni tâches planifiées, ni blocs, ni ressources, ni widgets, ni rapporteurs de santé, ni aucun autre comportement actif à l'exécution.

La désinstallation reste « désactiver d'abord » et relève du stockage. Une désinstallation ordinaire ne doit supprimer que le répertoire du paquet du plugin situé dans le stockage et les enregistrements locaux de l'état d'activation. Elle ne doit pas supprimer les tables de base de données appartenant au plugin, sauf si un futur outil de nettoyage destructif est conçu intentionnellement avec confirmation explicite.

La surcharge des vues du cœur reste interdite par défaut. L'extension par plugin doit passer par les registres documentés ou les slots d'extension. Les plugins ne doivent pas remplacer les vues du paquet, patcher à la volée les services du produit, ajouter des fichiers de routes cachés ni s'appuyer sur des effets de bord arbitraires d'un include.

Les enregistrements du Plugin Catalog devraient inclure :

• métadonnées de la fiche du plugin : handle, libellé, description, fournisseur/auteur, catégories, tags, version stable actuelle, URL de documentation, captures d'écran, URL de support et URL du code source ou du gestionnaire de tickets lorsqu'elles existent
• métadonnées de version : version, date de publication, notes de version, URL des artefacts, sommes de contrôle, futures signatures, exigences minimales de l'hôte, notes de mise à niveau et état d'obsolescence
• métadonnées de compatibilité : produits hôtes pris en charge, contraintes de version prises en charge du produit hôte, versions de PHP/Laravel requises le cas échéant, services de plateforme pris en charge et exigences de migration/configuration
• métadonnées d'avis de sécurité et d'obsolescence : versions affectées, versions corrigées, sévérité, liens vers les avis, indicateurs d'insécurité, versions obsolètes, conseils de remplacement et état de blocage de l'installation/mise à jour
• métadonnées de vérification des artefacts : algorithme de somme de contrôle, valeur de la somme de contrôle, taille de l'artefact, données de signature futures, identité de la clé de signature et état d'intégrité
• URL de documentation, de captures d'écran et de support : documentation publique, journal des modifications, guide de configuration, captures d'écran, contact de support, gestionnaire de tickets et profil du fournisseur
• matrice de compatibilité des produits hôtes : une ligne par produit hôte pris en charge, avec le handle du produit, son libellé, les contraintes de version compatibles, les métadonnées de classe de fournisseur lorsque nécessaire, les points d'extension utilisés, les exigences de configuration et les limitations connues

Les métadonnées du catalogue devraient être utiles avant le téléchargement, avant l'installation, avant l'activation, avant la configuration ou la migration et avant l'application d'une mise à jour.

Le futur Plugin Catalog pourra réutiliser des idées du flux actuel de métadonnées de mise à jour de WebBlocks Publisher, y compris les métadonnées de version, les sommes de contrôle des artefacts, les manifestes et les concepts de distribution hébergée. La publication au catalogue de plugins devrait malgré tout être documentée comme une capacité produit distincte.

Ce document ne présuppose pas une implémentation au sein du code actuel de WebBlocks Publisher. plugins.webblocksui.com pourra plus tard être propulsé par WebBlocks Publisher, par une application de catalogue dédiée ou par un site WebBlocks CMS doté d'un plugin de catalogue. Le choix d'implémentation devrait être fait une fois le contrat de métadonnées du catalogue et la frontière produit clarifiés.

Voir Plugin System pour l'architecture actuelle de l'hôte de plugins de WebBlocks CMS.

Le téléversement et l'installation manuelle de ZIP dans le CMS restent la méthode d'installation de plugins actuellement prise en charge. Les plugins téléversés s'installent dans des chemins relevant du stockage, restent désactivés par défaut et exigent des actions explicites d'activation et de configuration/migration. Les plugins désactivés et incompatibles restent inertes.

Le travail sur le catalogue/la boutique devrait s'appuyer sur le cycle de vie des plugins déjà existant dans le CMS plutôt que le remplacer. La future découverte au catalogue, les liens de téléchargement manuel, les flux d'installation depuis le catalogue, les vérifications de mise à jour et les actions contrôlées d'application des mises à jour devraient réutiliser les mêmes règles de handle, de compatibilité, de désactivation par défaut, de configuration requise, de disponibilité du schéma, de permissions, de propriété des routes et de sûreté à la désinstallation.

Cette phase n'inclut pas :

• l'implémentation à l'exécution
• l'installation distante automatique
• l'application automatique des mises à jour de plugins
• le comportement de marketplace payant
• le comportement d'un serveur de licences
• le flux d'approbation par des tiers
• l'automatisation du déploiement en production
• la vérification sur le site en production