Contributions avancées du SDK

Hooks, filtres et transactions#

PluginDefinition expose des hooks nommés pour contenus, médias, profils, activation et rendu. Un hook reçoit une copie du payload et un contexte typé ; un filtre retourne la valeur suivante. L’ordre suit la priorité de -1000 à 1000, puis l’identifiant de l’extension. La priorité par défaut est 10.

Une erreur arrête la chaîne et annule la transaction SQL courante. Elle n’annule pas un effet externe déjà envoyé. Utilisez context.authorize(permission) pour vérifier des droits frais ; un contexte système ne devient pas un utilisateur autorisé.

Les déclarations historiques restent compatibles. Une même clé de callback ne peut pas réentrer dans sa chaîne causale et la profondeur maximale est dix. Il n’existe pas de hook user.deleted sans parcours correspondant de suppression d’utilisateur.

Préserver l’identité en arrière-plan#

Les événements user.created, plugin.updated, content.published, backup.completed et job.failed créent des tâches durables dans la transaction métier. Le handler reçoit context.event avec un identifiant stable et une date. La livraison peut être rejouée : rendez les effets idempotents.

Une tâche issue d’une action utilisateur conserve son identité, sa version et son plafond de permissions. Les droits sont relus au traitement et intersectés avec ce plafond, y compris après un appel Bearer. Un changement de compte ou de rôle ne peut pas élargir les droits de la tâche. Les traitements réellement système gardent un acteur null.

Étendre les écrans existants#

Le serveur vérifie les permissions et les endpoints à chaque action. Une action d’éditeur doit contrôler l’identifiant et la version du contenu reçus. L’interface la désactive pendant une modification non enregistrée. Aucun JavaScript libre de plugin n’est chargé dans l’administration.

Décrire les endpoints et les webhooks#

schema.input et schema.output utilisent le sous-ensemble PluginJsonSchema du SDK. L’entrée est validée avant le handler et la sortie avant le commit. Un schéma accepte types, propriétés, items, enum, anyOf, bornes, longueurs, patterns et formats explicitement pris en charge ; aucun $ref distant ni coercition implicite n’est accepté.

Le CMS ajoute à OpenAPI les endpoints actifs accessibles et leurs schémas déclarés. Une ancienne extension sans schéma reste identifiée comme telle ; le CMS ne fabrique pas son contrat métier. Les endpoints privés de plugin ne deviennent pas accessibles par Bearer.

webhooks déclare jusqu’à vingt événements. services.webhooks.publish valide le payload et l’insère dans l’outbox. La destination, le secret et l’abonnement restent un choix explicite de l’exploitant dans Intégrations.

Enregistrer stockage, cache et e-mail#

storageProviders, cacheProviders et emailProviders déclarent jusqu’à cinq factories par catégorie. Elles reçoivent pluginId, settings, options et dataDirectory, sans dépendre des services CMS en cours d’amorçage. Le stockage retourne { identity, storage }, le cache son contrat et l’e-mail deliver({ to, subject, text }, deliveryId), avec close() facultatif. deliveryId reste stable lors des reprises ; une livraison externe peut être répétée.

Après installation et activation d’un package approuvé, sélectionnez plugin:bracten.s3/s3 dans CMS_STORAGE_PROVIDER, plugin:bracten.redis/redis dans CMS_CACHE_PROVIDER ou plugin:bracten.smtp/smtp dans CMS_EMAIL_TRANSPORT, puis redémarrez. Les variables serveur dédiées conservent adresses et secrets. Les options JSON CMS_STORAGE_PROVIDER_OPTIONS, CMS_CACHE_PROVIDER_OPTIONS et CMS_EMAIL_PROVIDER_OPTIONS restent vides pour ces factories officielles ; elles servent aux fournisseurs tiers. Les anciens sélecteurs s3, redis et smtp gardent leurs variables et ne dépendent pas de l’état des extensions, sans retrait programmé.

Seule la factory officielle correspondant exactement à son identifiant, son nom et son type reçoit context.transports.s3(), redis() ou smtp(). Cette capability sans argument s’utilise une fois pendant l’initialisation et retourne une façade sans client, secret ou configuration. La factory doit retourner ce résultat inchangé. L’adaptateur hôte établit l’identité S3 ; une valeur inventée par le package ne permet pas d’assimiler deux emplacements. Les autres factories n’obtiennent aucune capability officielle. La politique des modules reste inchangée et ce contrat ne constitue pas une sandbox.

Le runtime prépare les fournisseurs avant d’exposer HTTP et le scheduler, puis lie les handles seulement après validation des contrats et du binding de stockage. Un échec ferme les candidats, y compris un stockage au contrat incomplet, sans repli automatique ni publication d’un nouveau handle. Une sélection absente ou inactive bloque le démarrage. Désactivation, mise à jour et retrait du package sélectionné sont refusés ; pour un fournisseur officiel, reprenez explicitement son ancien sélecteur avec la même configuration avant la mise à jour, puis redémarrez avec le nouveau package.

Le stockage déclare une identité stable du jeu de données. Les sélecteurs s3 et plugin:bracten.s3/s3 sont équivalents seulement si l’empreinte hôte du bucket, de la région, du point d’accès et du préfixe correspond au binding. Aucun objet n’est déplacé ; changer de backend avec des médias ou objets existants exige une migration explicite. La restauration en place reconstruit les fournisseurs depuis l’état restauré ; un échec conserve le verrou. La CLI hors ligne sait utiliser l’adaptateur S3 officiel connu, avec une cible vide pour restore, mais refuse les stockages tiers non pris en charge. docs/providers.md détaille la mise à niveau et la reprise.

Les preuves locales des fournisseurs distinguent le serveur S3 protocolaire, Redis réel et SMTP TLS local des services de production. Elles couvrent les packages autonomes et le cycle de vie sans qualifier un bucket distant, un cluster Redis ou la délivrabilité SMTP externe.