Перейти до основного вмісту

Контракт з MPK

MPK — це контракт для виконання висновків, який міститься в скомпільованому архіві моделі. Це JSON-файл з назвою mpk.json або *_mpk.json, який використовується планувальником маршрутів і наступними модулями для вилучення даних. Самі архіви моделей є звичайними файлами .tar.gz, які завантажуються через Model.

На цій сторінці розглядаються два окремі аспекти:

  • Архів — це .tar.gz пакет, який містить бінарні файли, конфігурації, ваги. і JSON-файл контракту MPK.
  • Контракт — це JSON-документ *_mpk.json, який є основним джерелом інформації для логіка визначення маршруту.

Щодо правил безпеки та умов контракту на рівні байтів, див. Контракт MPK (ідентифікатор учасника).

Навіщо використовувати єдиний архів .tar.gz?​

Моделі на платформі Modalix містять багато рухомих частин (скомпільований граф MLA, ядра CVU, конфігурації, ваги). Об’єднання їх в один підписаний архів .tar.gz означає:

  • Атомарність — або вся модель завантажується, або жодна її частина не завантажується.
  • Версіонування — контракт MPK визначає версію своєї схеми; несумісні контракти. відхиляються на ранніх етапах.
  • Підтвердження походження — один артефакт, для якого обчислюється контрольна сума, створюється цифровий підпис і здійснюється доставка.
  • Відтворюваність — за умови використання одного й того ж архіву та контракту MPK, планувальник у рамках цієї системи приймає ті самі рішення щодо маршрутизації.

Контракт MPK є єдиним авторитетним документом у форматі JSON.​

Архів моделі може містити інші файли JSON; фреймворк розглядає лише mpk.json або *_mpk.json як контракт для здійснення висновків. Не намагайтеся визначити топологію моделі на основі інших файлів JSON в архіві — контракт передбачає, що «якщо це не вказано в контракті MPK, то цього не існує».

Це правило забезпечує детермінованість планувальника фреймворку.

Завантаження архіву моделі.​

Програми не викликають API для завантаження архіву безпосередньо. Створіть Model із шляхом до .tar.gz; Model виконує перевірку архіву, витягує безпечний вміст у внутрішню структуру, аналізує контракт MPK і запускає планування маршруту.

Приймаються лише точні архіви моделі у форматі .tar.gz (у нижньому регістрі). Файли .mpk, .tgz, .tar і прості файли .gz відхиляються до перевірки архіву.

Заходи безпеки​

Оскільки архіви моделей надходять із зовнішніх джерел, завантаження відбувається за принципом «за замовчуванням – відхилено». Кожен прийнятий архів проходить сувору перевірку:

  1. Список дозволених розширень — дозволено лише використання .tar.gz.
  2. Обмеження розміру — ліміти для архіву, окремого елемента та загального обсягу даних у байтах у форматі JSON.
  3. Обмеження кількості файлів — захищає від архівів, створених за принципом «zip-бомби».
  4. Обмеження глибини JSON — захищає від вичерпання ресурсів стеку аналізатора.
  5. Захист від обходу шляхів — нормалізовані шляхи відхиляють абсолютні шляхи та .. сегменти.
  6. Перевірка на відповідність стандарту UTF-8 — шляхи до файлів повинні бути коректними та відповідати стандарту UTF-8.
  7. Відхилення символів, що візуально схожі в Unicode — символи шляху, які візуально важко відрізнити, відхиляються.
  8. Список дозволених типів файлів — вилучаються лише відомі типи файлів.
  9. Відхилення JSON у разі наявності дублікатів ключів — будь-які дублікати ключів, незалежно від їхньої вкладеності, відхиляються.
  10. Перевірка схеми — метадані, що використовуються на стороні контракту та завантажувача, повинні відповідати підтримуваним схемам.
  11. Перевірка обов’язкових розділів — наявність контракту для виведення та бінарного файлу моделі є обов’язковою.
  12. Список дозволених ядер — усі ядра, на які робляться посилання, повинні бути в наборі, відомому для фреймворку.

Вищі рівні повідомляють про помилки у вигляді NeatError зі структурованими кодами помилок io.* або mpk.*.

Пов’язані типи​

  • Model — загальнодоступна точка входу, яка завантажує архіви моделей .tar.gz і надає доступ до фрагментів маршрутів.
  • MpkContract та пов’язані внутрішні структури — отриманий у результаті аналізу контракт для виведення даних з mpk.json / *_mpk.json.

Для подальшого ознайомлення​

  • Контракт MPK (ідентифікатор учасника) — правила на рівні байтів і семантика полів.
  • «Контракт MPK» — §0.16, §15, розділ, присвячений детальному аналізу проєкту.
  • «Матриця безпеки архіву моделей» — §91 розділу, присвяченого детальному аналізу проєкту.