Поставщики типов подключения

Пакет, поставщик и подключение

Библиотека хранит пакеты, а не активные процессы. Подписанный singleton-экземпляр поставщика с пустыми настройками и без сетевых grants активирует точную версию и digest только в желаемом и фактическом состоянии Running. Тогда его тип появляется в «Серверах». Каждое сохранённое подключение имеет отдельный приватный worker; эти процессы не являются дополнительными экземплярами поставщика. MQTT-сеанс нужен только поставщику, который явно использует MQTT-транспорт. Лимиты экземпляров и ресурсов сохраняются.

Подписанный декларативный каталог

Нужны singleton = true, минимум Plugin API 1.3 и один contribution connection-provider с ID пакета. Для прежнего MQTT-транспорта protocol_version = 3, для прямого источника protocol_version = 4 и assetSource: true. Это версия contribution, не новая версия SDK или Plugin API. Подписанное дерево включает schemas/connection-provider.json. Каталог задаёт provider, title, dataTitle, schemes, configSchema, uiSchema, непересекающиеся connectionFields и dataFields, operations. mqttServerId назначает хост только MQTT-поставщику. Протокол оборудования, типы данных и разбор импорта принадлежат плагину, а не списку протоколов в Core. Необязательные security и statusFields описывают стандартный редактор защиты и ограниченные поля состояния без JavaScript из пакета.

Операции и ограниченный транспорт

connection.validate проверяет {config}; connection.status сообщает состояние. Необязательный connection.import возвращает предпросмотр {mappings,issues}, который требует отдельного подтверждения и сохранения. Парные connection.security.get/update работают с приватными учётными данными и сертификатами под проверкой ревизий; секреты не входят в config и экспорт. Только защищённые workers получают одобренные tcp.connect:config:/endpoint:/endpoint и mqtt.publish-list:config:/mqttServerId:/mappings. Потоки /run/bluetraktor-source.sock и /run/bluetraktor-source-mqtt.sock ограничены точным endpoint и топиками; broker credentials плагину не выдаются. Это не разрешение произвольной сети или MQTT-подписки.

Прямой источник без MQTT

Для protocol 4 объявите assetSource: true и полный набор connection.browse, connection.assets, connection.snapshot, connection.watch, connection.changes. Поля mqttServerId и mappings, connection.import, discovery и MQTT-capabilities здесь не допускаются. Worker получает только одобренный TCP endpoint через /run/bluetraktor-source.sock. Core использует общий адаптер без зависимости от протокола оборудования или ID конкретного плагина.

instanceId всегда назначает хост: connection-server-<server_id>. path и paths относятся к этому источнику и не содержат адрес другого сервера. Хост проверяет точный пакет, желаемое состояние, ревизию конфигурации и права на исходный сервер; ответ старого поколения не принимается. Значения передаются прямо сборщику модели и подписчикам. Публикация готовой модели в MQTT выполняется обычным издателем модели, а не прямым поставщиком.

Дерево, снимок и изменения

@id имеет формат @ плюс JSON-массив [instanceId,...path]. Идентичность ноды должна быть устойчивой; name служит подписью, не ключом. Папки navigationOnly: true нельзя привязывать как значения. linkFields перечисляет доступные поля, которые добавляют последним сегментом ссылки. Не переносите MQTT-префиксы USEPI/ на прямые ссылки.

Epoch меняется при новом сеансе, ревизия монотонна внутри epoch. Не выдавайте устаревший ответ за снимок нового сеанса. connection.changes возвращает только запрошенные наблюдаемые пути; дубликаты, чужие пути, неверные ревизии и смена epoch между страницами отвергаются. Снимок должен сохранять числа, логические значения, строки и массивы без неявного преобразования типов.

{
  "found": true,
  "value": 12.5,
  "sourceEpoch": "fixture-session-1",
  "sourceRevision": "7"
}

Ограничения прямого источника

Запрос и ответ ограничены 192 КиБ, вызов — 8 секундами. path содержит до 40 непустых сегментов, каждый до 256 байт без управляющих символов. assets возвращает до 129 элементов с уникальными ID своего источника; linkFields — до 16 имён из латинских букв, цифр и подчёркивания, до 64 байт каждое.

watch ограничен 1024 путями на источник. changes — до 64 путей и элементов на страницу, nextOffset должен продвигаться в пределах исходного запроса. Хост опрашивает изменения ограниченными партиями; поставщик обязан освобождать наблюдения по окончании своей ограниченной аренды и не накапливать бесконечную историю. Недоступность и отказ в доступе являются ошибкой, не значением 0 или пустой успешной выборкой.

При публикации каталога укажите числовое metadata.connectionProviderProtocolVersion, равное версии подписанного contribution. Новый магазин передаёт connectionProviderProtocolVersionMax=4; старый клиент без этого параметра при фильтрации по версии продукта/API получает только protocol 3 и пакеты без такого требования. Метаданные управляют поиском совместимого выпуска, но не заменяют проверку подписанного пакета менеджером.

Приватная защита и смена конфигурации

Общий контракт connection-provider не определяет внутренний протокол конкретного устройства. Приватные данные не включаются в config, импорт или экспорт. Подготовку защиты, проверку ревизий, остановку старого транспорта и применение нового состояния проверяйте в реализации поставщика; наличие операции в каталоге не доказывает её готовность.

При неопределённом результате сохранения не считайте обновление принятым и не повторяйте его вслепую. Сначала проверьте фактическую ревизию и состояние. Обычный Bridge с картой и прямой источник с деревом являются разными пакетами и контрактами; не объявляйте возможности одного по наличию другого.

Остановка и удаление

Остановка или удаление экземпляра поставщика блокирует workers и транспорт, сохраняя настройки серверов для восстановления. Удаление его точного пакета удаляет принадлежащие ему серверы и приватные поколения. Уже опубликованные MQTT-значения не очищаются. Пакет в библиотеке не заменяет работающий экземпляр; смена версии не выполняется автоматически.

Совместимость и отдельные сборки

Официальные Formulas 1.0.0 и OPC to MQTT Bridge 1.0.0 используют Plugin API 1.3. Публикация SDK не разрешает миграцию или удаление. Старые официальные пакеты не удаляются автоматически: сначала нужны согласованная миграция зависимостей и проверенная точка восстановления; пользовательские плагины не затрагиваются. Снятие выпуска с публикации является отдельным решением. Совместимость старых обычных бинарников API 1.0/1.1/1.2 и formula-provider protocol 2 с новым Manager сохраняется независимо от присутствия старого выпуска в каталоге. Установленные экземпляры никогда не переключаются автоматически. SDK release 1.0.0 отправляет Hello 1.3 и требует Manager 1.3 даже при меньшем диапазоне session. Для проверки используйте negotiated_api_minor() и TestHost::with_api_minor. Source kit 1.0.0, crate SDK 0.1.0 и Plugin API 1.3 имеют разные версии. Formulas и Bridge — необязательные плагины: исходники в plugins/formulas и plugins/opcua-bridge собираются независимо от продукта. Core предоставляет общие контракты расширений без привязки к конкретному протоколу этих плагинов.

Граница публикации и миграции

Общедоступный SDK и собственная подпись не разрешают привилегированный каталог: нужны подпись издателя и отдельное одобрение contribution. Обычный community packager и студия не выпускают такой каталог; используйте согласованный процесс выпуска и проверку целевого Manager. Старые connection-provider protocol 1/2 проверяются, но не запускаются как protocol 3; их записи и приватные данные требуют явной миграции с резервной копией. Перед обновлением проверьте источники, установленные экземпляры и их зависимости в каждой конкретной установке. Сохраняйте работающие подключения, записи и приватные данные до согласованной миграции и проверки восстановления из резервной копии.

Config ограничен 192 КиБ и 8192 JSON-узлами, mappings — 4096 записями. Импорт браузера ограничен 128 КиБ, а экранированный запрос должен помещаться в 192 КиБ. Проверки SDK не удостоверяют изоляцию Linux, все режимы защиты, совместимость с оборудованием или запуск на ARM64.