Netpulse_SasS/db/profiles/build.py

#!/usr/bin/env python3
"""
Збирає міграцію ncm.profiles із каталогу команд.

Каталог (`catalog.json`) — джерело істини. Міграція з нього
породжується, а не правиться руками: інакше два описи одного й того
самого розійшлися б із першою ж правкою, і невідомо було б, який із них
справжній.

Каталог описує ДВІ речі про кожну платформу, і виходять вони в різні
файли:

  * як конфіг ЗНЯТИ (`config`, `prepare`, родина) — у міграцію
    0014_ncm_profiles.sql, тобто в самі рядки ncm.profiles;
  * як конфіг ЗАЛИТИ (блок `apply`) — у apply.generated.sql, окремим
    набором UPDATE.

Розділені вони не з естетики. Колонки ncm.profiles.apply_* заводить
міграція 0060, яка йде ПІСЛЯ 0014: вставка в 0014 не може згадати
колонку, якої на той момент ще немає. До того ж 0014 уже накочена на
стендах, а runner міграцій звіряє sha256 застосованих файлів і зупиняє
накат на розбіжності — будь-яка зміна тексту 0014 зупинила б оновлення
всім. Тому 0014 лишається байт-у-байт таким, як є, а поля заливки
їдуть окремим файлом.

Використання:

    python build.py                 # перезбирає обидва файли
    python build.py --check         # лише звіряє, чи вони актуальні
"""
import json
import pathlib
import re
import sys

HERE = pathlib.Path(__file__).parent
CATALOG = HERE / "catalog.json"
# Міграції переїхали в server/migrations: netpulse-migrate вшиває їх
# через //go:embed, а embed не бачить нічого за межами свого модуля
# (див. db/README-migrations.md). Шлях на db/migrations, що лишався тут
# після переїзду, вів у неіснуючий каталог: --check завжди звітував
# «розійшлася», а звичайний запуск падав на записі.
MIGRATION = HERE.parent.parent / "server" / "migrations" / "0014_ncm_profiles.sql"
# Не міграція, а заготовка для неї: номер міграції призначає людина,
# генератор не має права його вигадувати — паралельні гілки розберуть
# ті самі номери й зіткнуться.
APPLY_SQL = HERE / "apply.generated.sql"

# Значення за замовчуванням для полів заливки.
#
# Це не вибір генератора, а DEFAULT відповідних колонок із 0060: профіль
# без блоку `apply` має лишитись рівно таким, яким його зробив ALTER
# TABLE. Розбіжність тут означала б, що перезапуск генератора мовчки
# міняє поведінку вже налаштованих профілів.
APPLY_DEFAULTS = {
    "enter": [],
    "exit": [],
    "commit": None,
    "negate": None,
    "block_exit": "exit",
    "supported": False,
    "note": None,
}


def sql_str(v: str) -> str:
    return "'" + v.replace("'", "''") + "'"


def sql_opt(v) -> str:
    """NULL, а не порожній рядок: для apply_negate це різні речі.

    Порожній рядок означав би «заперечувати рядок префіксом ''», тобто
    відправити на пристрій команду без заперечника — рівно навпаки до
    задуманого. NULL чесно означає «родина не вміє прибрати рядок».
    """
    return "NULL" if v is None else sql_str(v)


def sql_json(obj) -> str:
    return sql_str(json.dumps(obj, ensure_ascii=False))


def build_commands(profile: dict, family: dict) -> list:
    """Повна послідовність: підготовка консолі, потім сам конфіг."""
    cmd = profile["config"]

    # Частина пристроїв «мережеві» лише зовні: конфіг знімається шелом.
    # Відправити в bash «terminal datadump» означало б гарантовану
    # помилку на кожному зборі.
    shellish = bool(re.match(r"(cat|tail|less|more /|sh\b|/)", cmd))

    out = []
    if family.get("pager") and not shellish:
        out.append(family["pager"])
    out.extend(profile.get("prepare", []))
    out.append(cmd)
    return out


def render(catalog: dict) -> str:
    families = catalog["families"]
    # Число рахуємо, а не пишемо руками: зашитий у текст лічильник
    # розходиться з дійсністю на першій же доданій платформі.
    n_platforms = len(catalog["profiles"])
    n_vendors = len({p["vendor"] for p in catalog["profiles"]})
    lines = [
        "-- =====================================================================",
        "-- NetPulse :: 0014_ncm_profiles.sql",
        f"-- Каталог команд збору конфігу: {n_platforms} платформ, {n_vendors} вендорів.",
        "--",
        "-- ФАЙЛ ЗГЕНЕРОВАНО. Джерело — db/profiles/catalog.json.",
        "-- Правити тут безглуздо: наступна збірка перезапише. Щоб додати",
        "-- платформу, відредагуй каталог і виконай db/profiles/build.py.",
        "--",
        "-- Промпти й команди вимкнення пейджера задані за родиною CLI й",
        "-- перевіряються на живому залізі перед промисловим ужитком: одна",
        "-- родина покриває десятки платформ, і дрібні відхилення трапляються.",
        "-- =====================================================================",
        "",
    ]

    for p in catalog["profiles"]:
        fam = families.get(p.get("family", "generic"), families["generic"])
        commands = build_commands(p, fam)

        note = []
        if p.get("startup"):
            note.append(f"startup: {p['startup']}")
        if p.get("strip_lines"):
            note.append(f"службових рядків на початку: {p['strip_lines']}")
        if p.get("alternatives"):
            note.append("альтернативи: " + ", ".join(p["alternatives"]))
        if note:
            lines.append("-- " + "; ".join(note))

        lines += [
            "INSERT INTO ncm.profiles",
            "  (tenant_id, key, name, vendor, transport, commands, prompt_regex,",
            "   enable_required, scrub_patterns, redact_patterns, is_builtin)",
            "VALUES (NULL, {}, {}, {}, 'ssh', {}, {},".format(
                sql_str(p["key"]), sql_str(p["name"]), sql_str(p["vendor"]),
                sql_json(commands), sql_str(fam["prompt"])),
            "        {}, {}, {}, true)".format(
                "true" if fam.get("enable_required") else "false",
                sql_json(fam.get("scrub", [])), sql_json(fam.get("redact", []))),
            "ON CONFLICT DO NOTHING;",
            "",
        ]

    return "\n".join(lines)


def apply_entries(catalog: dict) -> list:
    """Пари (ключ профілю, блок заливки) в порядку каталогу.

    Два джерела, бо профілі теж із двох. Ті, що описані каталогом,
    несуть `apply` поруч із командою збору — інакше нова платформа
    з'явилась би без полів заливки, і відкат для неї мовчки не працював
    би. Ті, що заведені окремими міграціями (zte-zxan — 0028, dlink-me —
    0034/0043), у каталозі профілю не мають, але їхня заливка описана
    тут же, у `apply_external`: тримати частину відповідей у каталозі, а
    частину — в разовій міграції означало б знову два джерела істини.
    """
    out = []
    for p in catalog["profiles"]:
        if "apply" in p:
            out.append((p["key"], p["apply"]))
    for key, ap in catalog.get("apply_external", {}).items():
        out.append((key, ap))
    return out


def render_apply(catalog: dict) -> str:
    """UPDATE-и, що переносять блоки `apply` каталогу в ncm.profiles."""
    lines = [
        "-- =====================================================================",
        "-- NetPulse :: поля заливки конфігу для вбудованих профілів",
        "--",
        "-- ФАЙЛ ЗГЕНЕРОВАНО. Джерело — db/profiles/catalog.json (блоки",
        "-- `apply` у профілях і секція `apply_external`). Правити тут",
        "-- безглуздо: наступна збірка перезапише.",
        "--",
        "-- ЦЕ НЕ МІГРАЦІЯ і сама вона нікуди не накочується. Номер міграції",
        "-- призначає людина, а не генератор: над одним каталогом номерів",
        "-- працюють паралельні гілки, і вигаданий номер зіткнувся б із чужим.",
        "-- Щоб зміни доїхали до бази, скопіюй цей текст у нову міграцію.",
        "--",
        "-- Чому не в 0014, звідки беруться самі профілі: колонки apply_*",
        "-- заводить 0060, тобто ПІЗНІШЕ, — вставка в 0014 не може згадати",
        "-- колонку, якої ще немає. І 0014 уже накочена на стендах, а runner",
        "-- звіряє sha256 застосованих файлів: зміна її тексту зупинила б",
        "-- накат усім.",
        "--",
        "-- Повторний накат безпечний: UPDATE задає всі поля явно, тож",
        "-- результат залежить лише від каталогу, а не від того, що вже",
        "-- стояло в рядку.",
        "-- =====================================================================",
        "",
    ]

    for key, ap in apply_entries(catalog):
        # Друкарська помилка в назві поля інакше пройшла б мовчки: `.get`
        # підставив би замовчування, і профіль поїхав би на пристрій із
        # чужими командами замість описаних.
        unknown = set(ap) - set(APPLY_DEFAULTS) - {"comment"}
        if unknown:
            raise SystemExit(f"{key}: невідомі поля заливки: {sorted(unknown)}")

        def field(name):
            return ap.get(name, APPLY_DEFAULTS[name])

        # Причина рішення їде поруч із рішенням. Порожнє місце над
        # `apply_supported = false` читалось би як недогляд, хоча за ним
        # стоїть розбір родини.
        comment = ap.get("comment") or []
        for line in [comment] if isinstance(comment, str) else comment:
            lines.append(("-- " + line).rstrip())
        lines += [
            "UPDATE ncm.profiles SET",
            "  apply_enter      = {}::jsonb,".format(sql_json(field("enter"))),
            "  apply_exit       = {}::jsonb,".format(sql_json(field("exit"))),
            "  apply_commit     = {},".format(sql_opt(field("commit"))),
            "  apply_negate     = {},".format(sql_opt(field("negate"))),
            "  apply_block_exit = {},".format(sql_str(field("block_exit"))),
            "  apply_supported  = {},".format(
                "true" if field("supported") else "false"),
            "  apply_note       = {}".format(sql_opt(field("note"))),
            "WHERE tenant_id IS NULL AND key = {};".format(sql_str(key)),
            "",
        ]

    return "\n".join(lines)


def main():
    catalog = json.loads(CATALOG.read_text(encoding="utf-8"))
    outputs = [(MIGRATION, render(catalog)), (APPLY_SQL, render_apply(catalog))]

    if "--check" in sys.argv:
        stale = []
        for path, sql in outputs:
            current = path.read_text(encoding="utf-8") if path.exists() else ""
            if current != sql:
                stale.append(path.name)
        if stale:
            print("розійшлося з каталогом: " + ", ".join(stale) +
                  " — виконай build.py", file=sys.stderr)
            return 1
        print("згенероване актуальне")
        return 0

    for path, sql in outputs:
        # Пишемо байтами, а не текстом: у текстовому режимі Python на
        # Windows сам перекладає \n у \r\n. Для згенерованої 0014 це не
        # косметика — runner міграцій звіряє sha256 файлу, вшитого в
        # бінарник, а CRLF-версія дає ІНШУ суму, ніж LF-версія з
        # репозиторію (.gitattributes: «у репозиторії — завжди LF»).
        # Збірка на Windows після запуску генератора інакше зупиняла б
        # накат на стенді з «міграцію 0014 змінено після застосування».
        path.write_bytes(sql.encode("utf-8"))
    vendors = len({p["vendor"] for p in catalog["profiles"]})
    print(f"{MIGRATION.name}: {len(catalog['profiles'])} платформ, {vendors} вендорів")
    print(f"{APPLY_SQL.name}: профілів із описаною заливкою: "
          f"{len(apply_entries(catalog))}")
    return 0


if __name__ == "__main__":
    sys.exit(main())