Написання додатків (плагінів)

Додатки додають функції до Antimatter зсередини: серверна частина на Go, яка підключається до сервера, і веб-додаток на React, який додає меню, панелі, типи повідомлень та сторінки. На цій сторінці показано, як організовано додаток, на прикладі вбудованого додатка «Опитування», і які зміни відбуваються в інтерфейсі Fusion Antimatter.

Як працює додаток

• Серверна частина — це програма на Go. Сервер запускає її як окремий процес і спілкується з нею через RPC: він викликає хуки додатка (повідомлення збирається опублікувати, виконано команду…) і додаток викликає API плагінів сервера (створити запис, прочитати користувача, зберегти дані…). Вона також може надавати HTTP-маршрути під /plugins/<app id>/.
• Веб-додаток — це JavaScript-пакет, який завантажується в браузер разом із веб-додатком. Він реєструє компоненти React та колбэки в реєстрі: кнопку в меню, панель, спосіб відображення типу повідомлення.
• Обидві частини є необов’язковими. Додаток встановлюється як пакет .tar.gz, а системні адміністратори вмикають, вимикають та налаштовують його.

Antimatter запускає додатки, написані для Mattermost, і навпаки, за умови, що додаток використовує лише хуки, які є в обох. Див. Хуки, які є лише в Antimatter.

Структура пакета

Окремого стартового шаблона немає: почніть із невеликого вбудованого додатка, наприклад antimatter-plugin-polls або antimatter-plugin-todo, і змініть його ID та код. Додаток «Опитування» організовано так:

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

Необов’язково: папка public/, яка надається як є під /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: унікальний і незмінний; зазвичай використовується ім’я домену у зворотному порядку. Він визначає маршрути, збережені налаштування та події WebSocket.
• version: семантична версія. Вбудовані додатки не вказують її в plugin.json; їхній інструмент збірки бере її з останнього git-тегу v*.
• min_server_version: Antimatter повідомляє 12.0.0.
• settings_schema: сторінка налаштувань додатка в Системній консолі (див. Налаштування).

make apply копіює маніфест у server/manifest.go та webapp/src/manifest.ts; make manifest-check перевіряє його.

Серверна частина

Серверна частина імпортує той самий Go-модуль, що й додатки Mattermost, github.com/mattermost/mattermost/server/public, з проксі Go-модулів. Її main лише запускає додаток:

package main

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

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

Тип Plugin вбудовує plugin.MattermostPlugin, що надає йому p.API, та реалізує потрібні хуки:

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

Загальні хуки

Повний список з точними сигнатурами наведено в server/public/plugin/hooks.go; API — в server/public/plugin/api.go. Пакет pluginapi (server/public/pluginapi) обгортає API у зручніші допоміжні функції.

Корисні виклики API

• CreatePost, UpdatePost, SendEphemeralPost: публікуйте від імені бота додатка або від імені користувача.
• EnsureBotUser(&model.Bot{Username, DisplayName}): створюйте бота додатка один раз і отримуйте його ID.
• PublishWebSocketEvent("poll_updated", payload, &model.WebsocketBroadcast{ChannelId: id}): надсилайте подію веб-додатку. Вона надходить як custom_<app id>_poll_updated.
• OpenInteractiveDialog: відкриває діалог.
• LogInfo, LogError та інші: записує в журнал сервера, позначаючи запис ID додатка.
• GetUser, GetChannel, HasPermissionToChannel: перевіряйте, хто має право робити що, перед діями від імені користувача.

Додаток працює на кожному сервері кластера. Зберігайте стан у сховищі ключ-значення або в базі даних, а не лише в пам’яті.

Служба ШІ

Сервер Antimatter викликає моделі ШІ для додатків через з’єднання з моделями, які налаштував адміністратор (див. ШІ у посібнику адміністратора). Додаток ніколи не зберігає ключ провайдера: він вказує, від імені якої особи та де діє, а сервер перевіряє, чи має ця особа доступ до з’єднання в цьому місці, застосовує його обмеження та бюджети, рахує токени за особою та додатком і аудитує виклик без його вмісту.

ConnectionID у кожному запиті вибирає з’єднання, а Model — одну з його моделей (порожнє значення для моделі за замовчуванням з’єднання). Operation — це коротка мітка для записів використання та аудиту, ніколи не вміст. Мінімальна версія сервера — 11.11.

Ці методи та пакет ai (server/public/ai) існують лише в копії модуля Antimatter, а не в версії, опублікованій Mattermost. Щоб ними скористатися, збирайте код проти server/public Antimatter, додавши рядок replace у ваш go.mod, наприклад replace github.com/mattermost/mattermost/server/public => ../antimatter/server/public. Такий додаток працюватиме лише на Antimatter.

Зберігання даних

Кожен додаток має власне сховище ключ-значення в базі даних сервера:

• KVSet(key, value), KVGet(key), KVDelete(key): значення — це байти, зазвичай JSON. Ключі — не довше 150 символів.
• KVSetWithExpiry(key, value, seconds): значення зникає після зазначеного часу.
• KVCompareAndSet(key, old, new) та KVSetWithOptions з Atomic: безпечні оновлення, коли кілька запитів або сервери записують один і той самий ключ. Опитування зберігає кожен голос саме так і повторює спробу в разі конфлікту.
• KVList(page, perPage): ключі, сторінка за сторінкою.

Веб-додаткова частина

Бандл реєструє клас за допомогою window.registerPlugin. Його initialize отримує реєстр та сховище 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());

• Спільні бібліотеки. Веб-додаток надає React, ReactDOM, Redux, React Redux та React Intl: вказуйте їх як externals у webpack (React, ReactDOM, Redux, ReactRedux, ReactIntl), замість того щоб включати власні копії. Дивіться webpack.config.js в Опитуваннях.
• Виклики вашої серверної частини. Використовуйте ${window.basename}/plugins/<app id>/… з параметрами з Client4.getOptions() (з mattermost-redux/client): вони містять заголовки, які серверу потрібні, щоб прийняти запит від браузера.
• Ваш власний стан. registerReducer додає редьюсер, який зберігається під state['plugins-<app id>'].
• Типи. Додаткові методи реєстру Antimatter відсутні в опублікованих типах Mattermost: Опитування декларує реєстр, який використовує, у webapp/src/types/host.ts.

Методи реєстру та їхні параметри задокументовано в коді, у webapp/fusion/src/plugins/registry.ts (Fusion) та webapp/channels/src/plugins/registry.ts (класичний).

Підтримка інтерфейсу Fusion

Antimatter має два веб-інтерфейси: Fusion (типовий) та класичний. Обидва завантажують ті самі бандли додатків і мають той самий реєстр, але Fusion малює багато елементів сам і розміщує компоненти додатків по-своєму. Перевірте ваш додаток в обох.

Визначення інтерфейсу

Перед завантаженням будь-якого додатка обидва інтерфейси встановлюють window.antimatterWebUI у 'fusion' або 'classic', а також те саме значення на кореневому елементі сторінки як data-am-web-ui. У Mattermost жодне з них не встановлюється.

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

Вбудовані застосунки використовують це для відмінного відображення. Опитування малює свої картки та діалогове вікно створення у стилі Fusion і відкриває власне діалогове вікно для /poll у Fusion. Дзвінки та Голосові канали не відображають бічну панель та сповіщення-тости, які Fusion замінює власним інтерфейсом дзвінка. Застосунок Агентів розміщує свої дії ШІ в меню повідомлень як групу під Інші дії, замість панелі інструментів при наведенні. Власні класи CSS Fusion (з префіксом am-) та його шар діалогових вікон (елемент am-layer) — це те, що використовують ці застосунки для відповідності інтерфейсу; це не задокументований стабільний API.

Де Fusion відображає компоненти плагінів

Що Fusion не показує або не запускає

• registerPostDropdownMenuComponent (компонент у меню повідомлення), registerPostCardTypeComponent (картка повідомлення в правій панелі) та registerProductSwitcherMenuItem не показуються в основних видах Fusion. Замість першого використовуйте registerPostDropdownMenuAction.
• registerMessageWillBeUpdatedHook не запускається, коли повідомлення редагується в Fusion. Перевіряйте редагування на сервері за допомогою хука MessageWillBeUpdated.
• registerActionAfterChannelCreation запускається лише з класичного діалогового вікна створення каналу, яке Fusion відкриває з Інші опції… у своєму діалоговому вікні Створити канал.
• Компоненти панелі застосунків показуються незалежно від їхніх supportedProductIds.
• Маршрути з registerNeedsTeamRoute та registerCustomRoute зберігають класичну рамку сторінки, як і продукти.

Хуки, які є лише в Antimatter

Ці методи реєстрації не існують у Mattermost. Перевіряйте, що метод існує, перед викликом, щоб застосунок також працював там:

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

Додавати та керувати видами у виборнику емодзі

У Fusion вкладка вибору емодзі отримує проп pickerKit: компоненти, які вкладка Emoji використовує для власних переглядів додавання та керування, щоб перегляди вкладки виглядали однаково та залишалися всередині вибірника. Додатки GIFs і Memes використовують його для додавання та керування GIF, наклейками та шаблонами мемів. Він містить version (1), хуки usePickerView та useOnEscape, а також компоненти PickerViewButtons (кнопки + та керування поруч із полем пошуку), PickerViewFrame (перегляд зі стрілкою назад), PickerNotice, PickerField, PickerSearch, PickerDropZone та PickerManageList. Клавіша Escape повертає з перегляду до сітки вкладки. Перевірте, що проп присутній: інші хости його не включають, і тоді вкладка використовує власні діалоги. Типи описано у webapp/fusion/src/types/store/plugins.ts (EmojiPickerTabProps), а компоненти — у webapp/fusion/src/fusion/popovers/picker_views.tsx.

Панель у новому вікні

Fusion передає компоненту registerRightHandSidebarComponent два додаткові пропи, щоб Відкрити в новому вікні відкривало панель там, де вона була, а не на домашній сторінці додатка:

• setPanelState(state): викликайте, коли панель змінює місце, передаючи короткий рядок, який визначає ваш додаток, наприклад 'note/<id>' або 'board/<id>/card/<id>', або null для домашнього екрана. Це значення потрапляє до адреси вікна, тому ніколи не зберігайте в ньому конфіденційні дані. Стан довжиною понад 512 символів або з керувальними символами буде відкинуто.
• initialPanelState: у новому вікні — стан, який мала панель, або undefined. Вважайте його ненадійним вхідним даним: отримуйте елемент повторно від імені ввійшеної особи, а якщо вона не може його відкрити, показуйте домашній екран додатка або перегляд «не знайдено».

Стан забувається, коли панель закривається або на її місце приходить панель іншого додатка. Щоб відкрити вікно панелі самостійно, використовуйте popoutRhsPlugin (також доступний у window.WebappUtils.popouts), передаючи стан як необов’язковий п’ятий аргумент. Нотатки, Дошка для малювання, Список справ, Kanban та Плейбуки використовують саме це.

fusionIcon вказує на іконку з набору іконок Fusion (наприклад poll, sticker, calendar або image; див. webapp/fusion/src/fusion/components/icon). Fusion показує її замість icon, щоб елемент гармонійно вписувався в загальний стиль.

Налаштування

settings_schema у plugin.json описує сторінку додатка в Системна консоль › Плагіни:

"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."}
  ]
}

Типи налаштувань: bool, text, longtext, number, dropdown, radio, generated (випадковий секрет), username та custom (відображається компонентом, який веб-додаток реєструє за допомогою registerAdminConsoleCustomSetting). Налаштування можна групувати в sections.

Серверна частина читає їх у структуру, поля якої відповідають ключам:

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
}

Адміністратори також можуть встановити їх у конфігурації, у розділі PluginSettings.Plugins.<app id>, з ключами в нижньому регістрі (див. посібник адміністратора).

Переклади

Antimatter перекладено 37 мовами, а вбудовані додатки — теж. Веб-додаток робить це так:

1. Написуйте кожний рядок за допомогою React Intl, з ID та англійським текстом: <FormattedMessage id='polls.create' defaultMessage='Create a poll'/> або defineMessages. Префіксуйте ID назвою вашого додатка.
2. Виділіть англійські рядки у webapp/i18n/en.json (вбудовані додатки використовують formatjs extract).
3. Додайте по одному файлу для кожної мови поруч із ним, з тими самими ID: fr.json, de.json, pt-BR.json, zh-CN.json…
4. Передайте їх веб-додатку, який запитує мову користувача:

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

Якщо рядок відсутній, використовується його англійський defaultMessage. Для рядків, які надсилає серверна частина (відповіді на команди, повідомлення ботів), пакет pluginapi/i18n завантажує файли перекладів, включені в пакет (наприклад, assets/i18n), і надає локалізатор мовою кожного користувача.

Збирання, встановлення та налагодження

Потрібні Go та Node.js (версія з .nvmrc додатка). У папці додатка:

make deploy та інші серверні команди використовують локальний сокет, якщо його знаходять (/var/tmp/antimatter_local.socket або AM_LOCALSOCKETPATH): запускайте їх на машині сервера з увімкненим локальним режимом. Інакше вони вхідять на сервер, заданий MM_SERVICESETTINGS_SITEURL, за допомогою AM_ADMIN_TOKEN або AM_ADMIN_USERNAME та AM_ADMIN_PASSWORD. Інструменти збирання ще не читають ім’я AM_ для URL сайту.

Ручне встановлення пакета

• Системний адміністратор дозволяє завантаження за допомогою AM_PLUGINSETTINGS_ENABLEUPLOADS=true (вимкнено за замовчуванням; у системній консолі немає перемикача).
• Потім Системна консоль › Плагіни › Керування плагінами › Завантажити плагін, або amctl plugin add weather.tar.gz, а потім amctl plugin enable com.example.weather.
• Якщо на сервері увімкнено Вимагати підпис плагіна, він приймає лише пакети, підписані ключем, якому довіряє; див. Встановлення інших додатків.