Écriture d'applications (plugins)

Les applications ajoutent des fonctionnalités à Antimatter depuis l'intérieur : une partie serveur en Go qui s'attache au serveur, et une partie application web en React qui ajoute des menus, des panneaux, des types de messages et des pages. Cette page montre comment une application est structurée, en utilisant l'application Sondage fournie comme exemple, et ce qui change dans l'interface Fusion d'Antimatter.

Fonctionnement d'une application

• La partie serveur est un programme Go. Le serveur le démarre en tant que processus séparé et communique avec lui via RPC : il appelle les hooks de l'application (un message est sur le point d'être publié, une commande a été exécutée…), et l'application appelle l'API plugin du serveur (créer un message, lire un utilisateur, stocker des données…). Elle peut également servir des routes HTTP sous /plugins/<app id>/.
• La partie application web est un bundle JavaScript chargé dans le navigateur avec l'application web. Elle enregistre des composants React et des rappels avec le registre : un bouton dans un menu, un panneau, une manière de dessiner un type de message.
• Chaque partie est facultative. Une application est installée sous forme de bundle .tar.gz, et les administrateurs système l'activent, la désactivent et la configurent.

Antimatter exécute les applications écrites pour Mattermost, et vice versa, tant qu'une application n'utilise que des hooks présents dans les deux. Voir Hooks spécifiques à Antimatter.

Structure du bundle

Il n'y a pas de modèle de démarrage séparé : commencez par une petite application fournie telle que antimatter-plugin-polls ou antimatter-plugin-todo, et modifiez son ID et son code. Sondage est structuré ainsi :

antimatter-plugin-polls/
├── plugin.json            the manifest
├── Makefile               build, test, bundle, deploy
├── build/                 the manifest and pluginctl helper tools (Go), setup.mk
├── assets/icon.svg        files shipped with the bundle
├── go.mod
├── server/
│   ├── main.go            plugin.ClientMain(&Plugin{})
│   ├── plugin.go          the Plugin type, OnActivate, ServeHTTP
│   ├── manifest.go        generated from plugin.json
│   ├── api.go, command.go, hooks.go, store.go …
│   └── dist/              compiled binaries, one per platform
└── webapp/
    ├── package.json, webpack.config.js, tsconfig.json
    ├── i18n/              en.json and one file per language
    ├── src/index.tsx      registers the app with the web app
    ├── src/manifest.ts    generated from plugin.json
    ├── src/translations.ts
    └── dist/main.js       the bundle

Facultatif : un dossier public/, servi tel quel à /plugins/<app id>/public/.

plugin.json

{
  "id": "com.example.weather",
  "name": "Weather",
  "description": "Forecasts in the chat.",
  "homepage_url": "https://github.com/example/weather",
  "support_url": "https://github.com/example/weather/issues",
  "icon_path": "assets/icon.svg",
  "version": "1.0.0",
  "min_server_version": "12.0.0",
  "server": {
    "executables": {
      "linux-amd64": "server/dist/plugin-linux-amd64",
      "linux-arm64": "server/dist/plugin-linux-arm64",
      "darwin-amd64": "server/dist/plugin-darwin-amd64",
      "darwin-arm64": "server/dist/plugin-darwin-arm64",
      "windows-amd64": "server/dist/plugin-windows-amd64.exe"
    }
  },
  "webapp": {"bundle_path": "webapp/dist/main.js"},
  "settings_schema": {"settings": []}
}

• id : unique et permanent ; un nom de domaine inversé est habituel. Il nomme les routes, les paramètres stockés et les événements WebSocket.
• version : version sémantique. Les applications fournies l'excluent de plugin.json ; leur outil de construction la prend du dernier tag git v*.
• min_server_version : Antimatter signale 12.0.0.
• settings_schema : la page des paramètres de l’application dans la Console système (voir Paramètres).

make apply copie le manifeste dans server/manifest.go et webapp/src/manifest.ts ; make manifest-check le valide.

La partie serveur

La partie serveur importe le même module Go que les applications Mattermost, github.com/mattermost/mattermost/server/public, depuis le proxy de modules Go. Son main ne fait que démarrer l’application :

package main

import "github.com/mattermost/mattermost/server/public/plugin"

func main() {
	plugin.ClientMain(&Plugin{})
}

Le type Plugin intègre plugin.MattermostPlugin, ce qui lui donne accès à p.API, et implémente les hooks dont il a besoin :

type Plugin struct {
	plugin.MattermostPlugin
	router *mux.Router
}

func (p *Plugin) OnActivate() error {
	p.router = p.newRouter()
	return p.API.RegisterCommand(&model.Command{
		Trigger:          "weather",
		AutoComplete:     true,
		AutoCompleteDesc: "Show the forecast",
		AutoCompleteHint: "[city]",
	})
}

func (p *Plugin) ExecuteCommand(c *plugin.Context, args *model.CommandArgs) (*model.CommandResponse, *model.AppError) {
	city := strings.TrimSpace(strings.TrimPrefix(args.Command, "/weather"))
	return &model.CommandResponse{
		ResponseType: model.CommandResponseTypeEphemeral,
		Text:         "Forecast for " + city + ": sunny",
	}, nil
}

func (p *Plugin) ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) {
	p.router.ServeHTTP(w, r)
}

Hooks courants

La liste complète, avec les signatures exactes, se trouve dans server/public/plugin/hooks.go ; l’API est dans server/public/plugin/api.go. Le paquet pluginapi (server/public/pluginapi) encapsule l’API dans des aides plus conviviales.

Appels d’API utiles

• CreatePost, UpdatePost, SendEphemeralPost : publier en tant que bot de l’application ou en tant qu’utilisateur.
• EnsureBotUser(&model.Bot{Username, DisplayName}) : créez le bot de l’application une seule fois et récupérez son identifiant.
• PublishWebSocketEvent("poll_updated", payload, &model.WebsocketBroadcast{ChannelId: id}) : envoyez un événement à l’application web. Il arrive sous la forme custom_<app id>_poll_updated.
• OpenInteractiveDialog : ouvrez une boîte de dialogue.
• LogInfo, LogError et leurs homologues : écrivez dans le journal du serveur, avec l’identifiant de l’application comme étiquette.
• GetUser, GetChannel, HasPermissionToChannel : vérifiez qui peut faire quoi avant d’agir au nom d’un utilisateur.

Une application s'exécute sur chaque serveur du cluster. Conservez l'état dans le magasin clé-valeur ou dans la base de données, et non uniquement en mémoire.

Le service IA

Le serveur Antimatter appelle des modèles IA pour les applications, via les connexions de modèles configurées par un admin (voir IA dans le guide d'administration). Une application ne détient jamais la clé d'un fournisseur : elle indique la personne pour laquelle elle agit et l'endroit où elle le fait, et le serveur vérifie que cette personne peut utiliser la connexion à cet endroit, applique ses limites et budgets, compte les jetons pour la personne et l'application, et audite l'appel sans son contenu.

Le ConnectionID de chaque requête sélectionne la connexion, et Model l'un de ses modèles (vide pour le modèle par défaut de la connexion). Operation est un libellé court pour les enregistrements d'utilisation et d'audit, jamais du contenu. Leur version minimale de serveur est 11.11.

Ces méthodes et le paquet ai (server/public/ai) n'existent que dans la copie du module d'Antimatter, pas dans la version publiée par Mattermost. Pour les utiliser, compilez contre server/public d'Antimatter avec une ligne replace dans votre go.mod, par exemple replace github.com/mattermost/mattermost/server/public => ../antimatter/server/public. Une telle application ne fonctionne que sur Antimatter.

Stockage des données

Chaque application dispose de son propre magasin clé-valeur dans la base de données du serveur :

• KVSet(key, value), KVGet(key), KVDelete(key) : les valeurs sont des octets, généralement au format JSON. Les clés font au maximum 150 caractères.
• KVSetWithExpiry(key, value, seconds) : la valeur disparaît après ce délai.
• KVCompareAndSet(key, old, new) et KVSetWithOptions avec Atomic : mises à jour sécurisées lorsque plusieurs requêtes ou serveurs écrivent la même clé. Polls enregistre chaque vote de cette manière et réessaie en cas de conflit.
• KVList(page, perPage) : les clés, page par page.

La partie application web

Le bundle enregistre une classe avec window.registerPlugin. Sa méthode initialize reçoit le registre et le magasin Redux :

import manifest from './manifest';

class Plugin {
    initialize(registry, store) {
        registry.registerTranslations((locale) => translationsFor(locale));
        registry.registerPostTypeComponent('custom_poll', PollPost);
        registry.registerWebSocketEventHandler(`custom_${manifest.id}_poll_updated`, (msg) => {
            store.dispatch(pollUpdated(JSON.parse(msg.data.poll)));
        });
        registry.registerReconnectHandler(() => store.dispatch(reloadPolls()));
    }
}

window.registerPlugin(manifest.id, new Plugin());

• Bibliothèques partagées. L'application web fournit React, ReactDOM, Redux, React Redux et React Intl : listez-les comme externals webpack (React, ReactDOM, Redux, ReactRedux, ReactIntl) plutôt que d'inclure vos propres copies. Consultez le webpack.config.js de Polls.
• Appeler votre partie serveur. Effectuez une requête vers ${window.basename}/plugins/<app id>/… avec les options de Client4.getOptions() (depuis mattermost-redux/client) : elles transportent les en-têtes dont le serveur a besoin pour accepter une requête provenant du navigateur.
• Votre propre état. registerReducer ajoute un reducer, stocké sous state['plugins-<app id>'].
• Types. Les méthodes supplémentaires du registre d'Antimatter ne figurent pas dans les types publiés de Mattermost : Polls déclare le registre qu'il utilise dans webapp/src/types/host.ts.

Les méthodes du registre et leurs paramètres sont documentées dans le code, dans webapp/fusion/src/plugins/registry.ts (Fusion) et webapp/channels/src/plugins/registry.ts (classique).

Prise en charge de l'interface Fusion

Antimatter dispose de deux interfaces web : Fusion, par défaut, et l'interface classique. Les deux chargent les mêmes bundles d'application et partagent le même registre, mais Fusion dessine elle-même de nombreux éléments et place les composants des plugins à sa manière. Testez votre application dans les deux interfaces.

Détecter l'interface

Avant le chargement de toute application, les deux interfaces définissent window.antimatterWebUI sur 'fusion' ou 'classic', et la même valeur sur l'élément racine de la page en tant qu'attribut data-am-web-ui. Sur Mattermost, aucune des deux n'est définie.

export function isFusionUI(): boolean {
    return window.antimatterWebUI === 'fusion' || document.documentElement.dataset.amWebUi === 'fusion';
}

Les applications intégrées utilisent cela pour se dessiner différemment. Les sondages affichent leurs cartes de sondage et leur boîte de dialogue de création dans le style de Fusion, et ouvrent leur propre boîte de dialogue pour /poll dans Fusion. Les appels et les canaux vocaux omettent les composants de barre latérale et de notification qui sont remplacés par l'interface d'appel propre à Fusion. L'application Agents place ses actions IA dans le menu des messages, en tant que groupe sous Plus d'actions, au lieu de la barre d'outils au survol. Les classes CSS propres à Fusion (préfixées par am-) et sa couche de boîte de dialogue (l'élément am-layer) sont ce que ces applications utilisent pour s'adapter à l'interface ; il ne s'agit pas d'une API documentée et stable.

Là où Fusion affiche les composants des plugins

Ce que Fusion n'affiche pas ou n'exécute pas

• registerPostDropdownMenuComponent (un composant du menu du message), registerPostCardTypeComponent (une carte d'un message dans le panneau de droite) et registerProductSwitcherMenuItem ne sont pas affichés dans les vues principales de Fusion. Utilisez registerPostDropdownMenuAction à la place du premier.
• registerMessageWillBeUpdatedHook ne s'exécute pas lorsqu'un message est modifié dans Fusion. Vérifiez les modifications côté serveur avec le hook MessageWillBeUpdated à la place.
• registerActionAfterChannelCreation ne s'exécute que depuis la boîte de dialogue de création de canal classique, que Fusion ouvre depuis Plus d’options… dans sa boîte de dialogue Créer un canal.
• Les composants de la barre d'application sont affichés quelle que soit leur valeur de supportedProductIds.
• Les routes de registerNeedsTeamRoute et registerCustomRoute conservent le cadre de page classique, comme les produits.

Des hooks propres à Antimatter

Ces méthodes d'enregistrement n'existent pas dans Mattermost. Vérifiez qu'une méthode existe avant de l'appeler, afin que l'application fonctionne également là-bas :

if (typeof registry.registerComposerMenuItem === 'function') {
    registry.registerComposerMenuItem({
        text: 'Create a poll',
        icon: <i className='icon icon-chart-bar'/>,
        fusionIcon: 'poll',
        action: ({channelId, rootId}) => openPollCreation(channelId, rootId),
    });
} else {
    registry.registerChannelHeaderButtonAction(icon, (channel) => openPollCreation(channel.id), 'Create a poll', 'Create a poll');
}

Ajouter et gérer des vues dans le sélecteur d'emojis

Dans Fusion, l'onglet du sélecteur d'emoji reçoit une prop pickerKit : les composants utilisés par l'onglet Emoji pour ses propres vues d'ajout et de gestion, afin que les vues d'un onglet aient le même aspect et restent à l'intérieur du sélecteur. Les applications GIFs et Memes l'utilisent pour ajouter et gérer les GIF, les autocollants et les modèles de mèmes. Elle contient version (1), les hooks usePickerView et useOnEscape, ainsi que les composants PickerViewButtons (les boutons + et de gestion situés à côté de la zone de recherche), PickerViewFrame (une vue avec sa flèche de retour), PickerNotice, PickerField, PickerSearch, PickerDropZone et PickerManageList. La touche Échap permet de revenir d'une vue à la grille de l'onglet. Vérifiez que la prop est présente : d'autres hôtes ne la fournissent pas, auquel cas l'onglet conserve ses propres boîtes de dialogue. Les types sont dans webapp/fusion/src/types/store/plugins.ts (EmojiPickerTabProps) et les composants dans webapp/fusion/src/fusion/popovers/picker_views.tsx.

Le panneau dans une nouvelle fenêtre

Fusion fournit deux props supplémentaires au composant de registerRightHandSidebarComponent, afin que Ouvrir dans une nouvelle fenêtre ouvre le panneau à l'endroit où il se trouvait plutôt qu'à l'accueil de l'application :

• setPanelState(state) : à appeler lorsque le panneau change d'emplacement, avec une courte chaîne définie par votre application, telle que 'note/<id>' ou 'board/<id>/card/<id>', ou null à son accueil. Elle est insérée dans l'adresse de la fenêtre, ne mettez donc jamais de secret dedans. Un état supérieur à 512 caractères, ou contenant des caractères de contrôle, est ignoré.
• initialPanelState : dans la nouvelle fenêtre, l'état que le panneau avait, ou undefined. Traitez-le comme une entrée non fiable : récuperez à nouveau l'élément en tant que personne connectée, et affichez l'accueil de l'application ou une vue « introuvable » si la personne ne peut pas l'ouvrir.

L'état est oublié lorsque le panneau se ferme ou qu'un panneau d'une autre application prend sa place. Pour ouvrir vous-même la fenêtre d'un panneau, popoutRhsPlugin (également dans window.WebappUtils.popouts) prend l'état comme cinquième argument facultatif. Notes, Tableau blanc, À faire, Kanban et Playbooks utilisent cette fonctionnalité.

fusionIcon désigne une icône du jeu d’icônes de Fusion (par exemple poll, sticker, calendar ou image ; voir webapp/fusion/src/fusion/components/icon). Fusion l’affiche à la place de icon, de sorte que l’élément corresponde aux autres.

Paramètres

settings_schema dans plugin.json décrit la page de l’application dans Console système › Plugins :

"settings_schema": {
  "header": "Forecasts come from the weather service below.",
  "settings": [
    {"key": "ServiceURL", "display_name": "Service URL", "type": "text", "default": "https://api.example.com"},
    {"key": "Units", "display_name": "Units", "type": "dropdown", "default": "metric",
     "options": [{"display_name": "Celsius", "value": "metric"}, {"display_name": "Fahrenheit", "value": "imperial"}]},
    {"key": "EnableAlerts", "display_name": "Severe weather alerts", "type": "bool", "default": false,
     "help_text": "Post alerts in the channels that follow a city."}
  ]
}

Types de paramètres : bool, text, longtext, number, dropdown, radio, generated (un secret aléatoire), username et custom (dessiné par un composant que la partie application web enregistre avec registerAdminConsoleCustomSetting). Les paramètres peuvent être regroupés dans des sections.

La partie serveur les lit dans une structure dont les champs correspondent aux clés :

type configuration struct {
	ServiceURL   string
	Units        string
	EnableAlerts bool
}

func (p *Plugin) OnConfigurationChange() error {
	var cfg configuration
	if err := p.API.LoadPluginConfiguration(&cfg); err != nil {
		return err
	}
	p.setConfiguration(&cfg)
	return nil
}

Les admins peuvent également les définir dans la configuration, sous PluginSettings.Plugins.<app id>, avec des clés en minuscules (voir le guide d’administration).

Traductions

Antimatter est traduit en 37 langues, tout comme les applications intégrées. La partie application web le fait ainsi :

1. Écrivez chaque chaîne avec React Intl, avec un ID et son texte en anglais : <FormattedMessage id='polls.create' defaultMessage='Create a poll'/> ou defineMessages. Préfixez les IDs avec le nom de votre application.
2. Extrayez les chaînes anglaises dans webapp/i18n/en.json (les applications intégrées utilisent formatjs extract).
3. Ajoutez un fichier par langue à côté, avec les mêmes IDs : fr.json, de.json, pt-BR.json, zh-CN.json…
4. Transmettez-les à l'application web, qui demande la langue de l'utilisateur :

   import fr from '../i18n/fr.json';
   import ptBR from '../i18n/pt-BR.json';
   
   const catalogs = {fr, 'pt-BR': ptBR};
   
   export function translationsFor(locale) {
       return catalogs[locale] || catalogs[locale.split('-')[0]] || {};
   }
   
   registry.registerTranslations(translationsFor);

Une chaîne manquante retombe sur son defaultMessage en anglais. Pour les chaînes envoyées par la partie serveur (réponses aux commandes, messages de bot), le paquet pluginapi/i18n charge les fichiers de traduction inclus dans le bundle (par exemple assets/i18n) et fournit un localisateur dans la langue de chaque utilisateur.

Compiler, installer et déboguer

Vous avez besoin de Go et de Node.js (la version indiquée dans le .nvmrc de l'application). Dans le dossier de l'application :

make deploy et les autres commandes serveur utilisent une socket de mode local s'ils en trouvent une (/var/tmp/antimatter_local.socket, ou AM_LOCALSOCKETPATH) : exécutez-les sur la machine du serveur avec le mode local activé. Sinon, elles se connectent au serveur indiqué par MM_SERVICESETTINGS_SITEURL avec AM_ADMIN_TOKEN, ou AM_ADMIN_USERNAME et AM_ADMIN_PASSWORD. Les outils de compilation ne lisent pas encore un nom AM_ pour l'URL du site.

Installer un bundle manuellement

• Un admin système autorise les envois avec AM_PLUGINSETTINGS_ENABLEUPLOADS=true (désactivé par défaut ; il n'y a pas d'interrupteur dans la Console système).
• Ensuite, Console système › Plugins › Gestion des plugins › Importer un plugin , ou amctl plugin add weather.tar.gz suivi de amctl plugin enable com.example.weather.
• Si le serveur a Nécessite une signature de plugin activé, il n'accepte que les bundles signés avec une clé qu'il fait confiance ; voir Installer d'autres applications.