Scrittura di app (plugin)

Le app aggiungono funzionalità ad Antimatter dall'interno: una parte server in Go che si aggancia al server e una parte app web in React che aggiunge menu, pannelli, tipi di messaggio e pagine. Questa pagina mostra come è strutturata un'app, usando l'app Sondaggio inclusa come esempio, e cosa cambia nell'interfaccia Fusion di Antimatter.

Come funziona un'app

• La parte server è un programma in Go. Il server lo avvia come processo separato e comunica con esso tramite RPC: chiama gli hook dell'app (un messaggio sta per essere pubblicato, un comando è stato eseguito…) e l'app chiama l'API plugin del server (crea un post, legge un utente, archivia dati…). Può anche servire route HTTP sotto /plugins/<app id>/.
• La parte app web è un bundle JavaScript caricato nel browser insieme all'app web. Registra componenti React e callback con il registry: un pulsante in un menu, un pannello, un modo per disegnare un tipo di messaggio.
• Ogni parte è facoltativa. Un'app viene installata come bundle .tar.gz e gli amministratori di sistema la abilitano, disabilitano e configurano.

Antimatter esegue app scritte per Mattermost e viceversa, purché un'app utilizzi solo hook presenti in entrambi. Vedi Hook solo in Antimatter.

La struttura del bundle

Non esiste un template di avvio separato: parti da una piccola app inclusa come antimatter-plugin-polls o antimatter-plugin-todo e modifica il suo ID e il codice. Polls è strutturata così:

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

Facoltativo: una cartella public/, servita così com'è in /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: univoco e permanente; è consuetudine usare un nome di dominio inverso. Definisce i nomi delle route, delle impostazioni archiviate e degli eventi WebSocket.
• version: versione semantica. Le app incluse omettono questo campo in plugin.json; il loro strumento di build lo ottiene dall'ultimo tag git v*.
• min_server_version: Antimatter riporta 12.0.0.
• settings_schema: la pagina delle impostazioni dell'app nella Console di Sistema (vedi Impostazioni).

make apply copia il manifesto in server/manifest.go e webapp/src/manifest.ts; make manifest-check lo valida.

La parte server

La parte server importa lo stesso modulo Go delle app Mattermost, github.com/mattermost/mattermost/server/public, dal proxy dei moduli Go. Il suo main si limita ad avviare l'app:

package main

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

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

Il tipo Plugin incorpora plugin.MattermostPlugin, che gli fornisce p.API, e implementa gli hook di cui ha bisogno:

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)
}

Hook comuni

L'elenco completo, con le firme esatte, si trova in server/public/plugin/hooks.go; l'API è in server/public/plugin/api.go. Il pacchetto pluginapi (server/public/pluginapi) avvolge l'API in helper più facili da usare.

Chiamate API utili

• CreatePost, UpdatePost, SendEphemeralPost: pubblicare come bot dell'app o come utente.
• EnsureBotUser(&model.Bot{Username, DisplayName}): creare il bot dell'app una sola volta e ottenerne l'ID.
• PublishWebSocketEvent("poll_updated", payload, &model.WebsocketBroadcast{ChannelId: id}): inviare un evento all'app web. Arriva come custom_<app id>_poll_updated.
• OpenInteractiveDialog: aprire un dialogo.
• LogInfo, LogError e simili: scrivere nel log del server, etichettato con l'ID dell'app.
• GetUser, GetChannel, HasPermissionToChannel: verificare chi può fare cosa prima di agire per conto di un utente.

Un'app viene eseguita su ogni server di un cluster. Conserva lo stato nello store key-value o nel database, non solo in memoria.

Il servizio AI

Il server di Antimatter chiama i modelli AI per le app, tramite le connessioni ai modelli configurate da un amministratore (vedi AI nella guida per amministratori). Un'app non detiene mai la chiave di un provider: indica la persona per cui agisce e il contesto, e il server verifica che tale persona possa utilizzare la connessione in quel contesto, applica i relativi limiti e budget, conteggia i token a carico della persona e dell'app e registra l'audit della chiamata senza il suo contenuto.

Il ConnectionID di ogni richiesta seleziona la connessione, e Model uno dei suoi modelli (vuoto per il modello predefinito della connessione). Operation è un'etichetta breve per i record di utilizzo e audit, mai il contenuto. La versione minima del server richiesta è 11.11.

Questi metodi e il pacchetto ai (server/public/ai) esistono solo nella copia del modulo di Antimatter, non nella versione pubblicata da Mattermost. Per utilizzarli, compila il progetto contro server/public di Antimatter aggiungendo una riga replace nel tuo go.mod, ad esempio replace github.com/mattermost/mattermost/server/public => ../antimatter/server/public. Un'app di questo tipo funziona solo su Antimatter.

Archiviazione dei dati

Ogni app dispone di un proprio store key-value nel database del server:

• KVSet(key, value), KVGet(key), KVDelete(key): i valori sono byte, di solito JSON. Le chiavi hanno al massimo 150 caratteri.
• KVSetWithExpiry(key, value, seconds): il valore scompare dopo il tempo specificato.
• KVCompareAndSet(key, old, new) e KVSetWithOptions con Atomic: aggiornamenti sicuri quando più richieste o server scrivono la stessa chiave. Polls salva ogni voto in questo modo e riprova in caso di conflitto.
• KVList(page, perPage): le chiavi, pagina per pagina.

La parte web app

Il bundle registra una classe con window.registerPlugin. Il suo initialize riceve il registro e lo store 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());

• Librerie condivise. La web app fornisce React, ReactDOM, Redux, React Redux e React Intl: elencale come externals di webpack (React, ReactDOM, Redux, ReactRedux, ReactIntl) anziché includere copie proprie. Consulta webpack.config.js di Polls.
• Chiamate alla parte server. Usa ${window.basename}/plugins/<app id>/… con le opzioni di Client4.getOptions() (da mattermost-redux/client): esse includono gli header necessari al server per accettare una richiesta dal browser.
• Il tuo stato. registerReducer aggiunge un reducer, memorizzato sotto state['plugins-<app id>'].
• Tipi. I metodi aggiuntivi del registro di Antimatter non sono inclusi nei tipi pubblicati di Mattermost: Polls dichiara il registro che utilizza in webapp/src/types/host.ts.

I metodi del registro e i relativi parametri sono documentati nel codice, in webapp/fusion/src/plugins/registry.ts (Fusion) e webapp/channels/src/plugins/registry.ts (classico).

Supporto per l'interfaccia Fusion

Antimatter dispone di due interfacce web: Fusion, quella predefinita, e quella classica. Entrambe caricano gli stessi bundle delle app e hanno lo stesso registro, ma Fusion disegna molti elementi in autonomia e posiziona i componenti dei plugin in modo proprio. Testa la tua app in entrambe.

Rilevamento dell'interfaccia

Prima che qualsiasi app venga caricata, entrambe le interfacce impostano window.antimatterWebUI a 'fusion' o 'classic', e lo stesso valore sull'elemento radice della pagina come data-am-web-ui. Su Mattermost, nessuno dei due è impostato.

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

Le app integrate usano questo per renderizzarsi in modo diverso. Polls disegna le sue schede di sondaggio e il suo dialogo di creazione nello stile di Fusion, e apre il proprio dialogo per /poll in Fusion. Le chiamate e i canali vocali omettono i componenti della barra laterale e delle notifiche a comparsa che Fusion sostituisce con la propria interfaccia di chiamata. L'app Agents posiziona le sue azioni AI nel menu dei messaggi, come un gruppo sotto Altre azioni, anziché nella barra degli strumenti al passaggio del mouse. Le classi CSS di Fusion (con prefisso am-) e il suo livello di dialogo (l'elemento am-layer) sono ciò che queste app usano per adattarsi all'interfaccia; non si tratta di un'API documentata e stabile.

Dove Fusion mostra i componenti dei plugin

Cosa Fusion non mostra o non esegue

• registerPostDropdownMenuComponent (un componente nel menu dei messaggi), registerPostCardTypeComponent (una scheda di un messaggio nel pannello a destra) e registerProductSwitcherMenuItem non vengono mostrati nelle viste principali di Fusion. Usa registerPostDropdownMenuAction al posto del primo.
• registerMessageWillBeUpdatedHook non viene eseguito quando un messaggio viene modificato in Fusion. Controlla le modifiche sul server con l'hook MessageWillBeUpdated invece.
• registerActionAfterChannelCreation viene eseguito solo dalla finestra di dialogo di creazione del canale classica, che Fusion apre da Altre opzioni… nella sua finestra di dialogo Crea canale.
• I componenti della barra delle app vengono mostrati indipendentemente dal loro supportedProductIds.
• Le route da registerNeedsTeamRoute e registerCustomRoute mantengono il classico riquadro della pagina, come i prodotti.

Hook solo Antimatter

Questi metodi di registro non esistono su Mattermost. Verifica che un metodo esista prima di chiamarlo, in modo che l'app funzioni anche lì:

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');
}

Aggiungi e gestisci le visualizzazioni nel selettore di emoji

In Fusion, una scheda del selettore di emoji riceve una proprietà pickerKit: i componenti che la scheda Emoji utilizza per le proprie viste di aggiunta e gestione, in modo che le viste di una scheda abbiano un aspetto uniforme e rimangano all'interno del selettore. Le app GIF e Meme la usano per aggiungere e gestire GIF, adesivi e modelli di meme. Contiene version (1), gli hook usePickerView e useOnEscape, e i componenti PickerViewButtons (i pulsanti + e di gestione accanto alla casella di ricerca), PickerViewFrame (una vista con la sua freccia di ritorno), PickerNotice, PickerField, PickerSearch, PickerDropZone e PickerManageList. Il tasto Esc torna dalla vista alla griglia della scheda. Verifica che la proprietà sia presente: altri host la omettono, e in tal caso la scheda mantiene i propri dialoghi. I tipi sono in webapp/fusion/src/types/store/plugins.ts (EmojiPickerTabProps) e i componenti in webapp/fusion/src/fusion/popovers/picker_views.tsx.

Il pannello in una nuova finestra

Fusion fornisce al componente di registerRightHandSidebarComponent due proprietà aggiuntive, in modo che Apri in una nuova finestra apra il pannello nella posizione in cui si trovava, anziché nella home dell'app:

• setPanelState(state): chiamala quando il pannello cambia posizione, con una stringa breve definita dalla tua app, come 'note/<id>' o 'board/<id>/card/<id>', oppure null nella sua home. Viene inserita nell'indirizzo della finestra, quindi non inserirvi mai informazioni riservate. Uno stato lungo più di 512 caratteri, o contenente caratteri di controllo, viene scartato.
• initialPanelState: nella nuova finestra, lo stato che il pannello aveva, oppure undefined. Trattalo come input non attendibile: recupera nuovamente l'elemento come persona autenticata e mostra la home dell'app o una vista di elemento non trovato se non è possibile aprirlo.

Lo stato viene dimenticato quando il pannello si chiude o quando il pannello di un'altra app ne prende il posto. Per aprire la finestra di un pannello manualmente, popoutRhsPlugin (disponibile anche in window.WebappUtils.popouts) accetta lo stato come quinto argomento facoltativo. Note, Lavagna, Da fare, Kanban e Playbook utilizzano questa funzione.

fusionIcon specifica un'icona del set di icone di Fusion (ad esempio poll, sticker, calendar o image; vedere webapp/fusion/src/fusion/components/icon). Fusion la mostra al posto di icon, in modo che l'elemento sia coerente con gli altri.

Impostazioni

settings_schema in plugin.json descrive la pagina dell'app in Console di Sistema › 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."}
  ]
}

Tipi di impostazione: bool, text, longtext, number, dropdown, radio, generated (un segreto casuale), username e custom (disegnata da un componente registrato dalla parte web app con registerAdminConsoleCustomSetting). Le impostazioni possono essere raggruppate in sections.

La parte server le legge in una struct i cui campi corrispondono alle chiavi:

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
}

Gli amministratori possono anche impostarle nella configurazione, sotto PluginSettings.Plugins.<app id>, con chiavi in minuscolo (vedere la guida per amministratori).

Traduzioni

Antimatter è tradotto in 37 lingue, così come le app integrate. La parte web app lo fa in questo modo:

1. Scrivi ogni stringa con React Intl, con un ID e il suo testo in inglese: <FormattedMessage id='polls.create' defaultMessage='Create a poll'/> o defineMessages. Prefissa gli ID con il nome della tua app.
2. Estrai le stringhe in inglese in webapp/i18n/en.json (le app integrate usano formatjs extract).
3. Aggiungi un file per ogni lingua accanto a questo, con gli stessi ID: fr.json, de.json, pt-BR.json, zh-CN.json…
4. Passali alla web app, che richiede la lingua dell'utente:

   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);

Una stringa mancante ricade sul defaultMessage in inglese. Per le stringhe inviate dalla parte server (risposte ai comandi, messaggi dei bot), il pacchetto pluginapi/i18n carica i file di traduzione inclusi nel bundle (ad esempio assets/i18n) e fornisce un localizzatore nella lingua di ciascun utente.

Compila, installa e debugga

Ti servono Go e Node.js (la versione indicata nel file .nvmrc dell'app). Nella cartella dell'app:

make deploy e gli altri comandi server usano un socket locale quando ne trovano uno (/var/tmp/antimatter_local.socket, oppure AM_LOCALSOCKETPATH): eseguili sulla macchina del server con la modalità locale attiva. In caso contrario, accedono al server indicato da MM_SERVICESETTINGS_SITEURL usando AM_ADMIN_TOKEN, oppure AM_ADMIN_USERNAME e AM_ADMIN_PASSWORD. Gli strumenti di compilazione non leggono ancora un nome AM_ per l'URL del sito.

Installa un bundle manualmente

• Un amministratore di sistema consente i caricamenti con AM_PLUGINSETTINGS_ENABLEUPLOADS=true (disabilitato di default; non c'è un interruttore nella Console di Sistema).
• Poi Console di Sistema › Plugins › Gestione plugin › Carica Plugin, oppure amctl plugin add weather.tar.gz seguito da amctl plugin enable com.example.weather.
• Se sul server è attiva l'opzione Richiedi firma plugin, accetta solo bundle firmati con una chiave di cui si fida; consulta Installazione di altre app.