Есть счастливые люди, которые могут себе позволить просто перезаписывать YAML конфиги в продакшене. Мне же повезло меньше - инсталляции у меня специфичные и конфиги часто настраиваются "под себя". К каждому релизу приходилось готовить отдельную доку для ручного апдейта конфигурации.
Естественно, что руки сами тянутся автоматизировать такое безобразие, но гугл быстро дал понять что не я один мечтаю о хорошем, только вот заветного оазиса пока никто не нашел. Нет, смержить два YAML файлика задача не трудная, но только если готов пожертвовать комментами (что для многих, как и для меня, недопустимо).
Как вы уже могли догадаться, тулзу я в итоге написал свою (java). Но рассказать я хочу не о том что она умеет, а о том что было после "да что я сам не сделаю что ли...".
Кода не будет, просто описание того с чем пришлось иметь дело и что в итоге пришлось сделать (что гораздо интереснее скучных циклов). Заранее извиняюсь за обилие англицизмов.
Минимальный парсер, для случая одного дерева в файле (без ссылок) пишется за один присест. А вот финальная модель для него сложилась не сразу.
Правило для комментов тоже родилось сразу: "все что выше свойства это его коммент". Ну идеально же, так можно элементарно воссоздать файл 1-в-1 (а учитывая что чаще в апдейтах конфигов свойства добавляются без перемешивания остального, так вообще идеально). Для примера:
# Это все
# коммент для prop
prop:
# Это коммент для sub (включая пустую строку сверху)
sub: 1
# А это коммент для sub2 (отступ не важен)
sub2: 2
Еще одной важной вехой был принцип: одна нода (модели) - одна строчка файла (ну плюс строки коммента сверху конечно). Это и просто для понимания (при дебаге) и крайне удобно для записи модели обратно в файл.
Значение свойства само по себе не важно: для мержа достаточно имени. Поэтому можно принять за значение все что дальше двоеточия. Так и оригинальное форматирование сохраняется и инлайн комменты остаются.
prop: val # inline comment
multiline: some very
very very # с крмментарием
long value
Собсвенно, мультилайны определили вид value для нод как List<String>. По большому счету, главной проблемой было лишь определение где мультилайн заканчивается: значение сохраняется 1-в-1 (для того чтобы можно было его записать обратно без изменений), но вот отделить его от нижеследующего коммента крайне важно.
list:
- one
- two
Тут принцип одна строчка файла - одна нода ложиться идеально.
А может содержать объекты:
list:
- one: 1
two: 2
И вот тут то правило "одна нода - одна строчка" осеклось. Нет, я честно уперся рогом и долго пытался его придерживаться - получилось мягко говоря не очень: one: 1 был рутовой нодой (обозначающей объект списка), а все что дальше его детьми.
Пример ниже окончательно зарубил такой подход:
list:
- one: 1
sub: s
two: 2
(sub и two сливались в один список)
Пришлось вводить группирующую ноду (и сразу дышать стало легче). Так же это очень пригодилось когда вспомнил что листы могут записываться и так (spring boot любит такое написание):
list:
-
one: 1
two: 2
Естественно, большенство этих мутаций модели повылезали на этапе отладки мержера, но о нем отдельно.
Во-первых, могут измениться отступы:
Было:
level:
one: 1
Стало:
level:
one: 1
two: 2
Если мержить "в лоб" будет не валидный YAML:
level:
one: 1
two: 2
Значит нужно всегда переформатировать старые ноды согласно новым отступам (неважно в какую сторону). Причем крайне важно сдвигать все поддерево, а то можно порушить листы или мультилайны (которые очень завязаны на оступы). В рамках свойтва обязательно должны "съезжать" коммент и значение. Например, если сдвинуть только свойство здесь:
prop:
# комментарий
multiline: long long
long value
Получится некрасивый коммент и невалидное значение (ошибка синтаксиса):
prop:
# комментарий
multiline: long long
long value
Дальше - порядок свойств. Что если в новом конфиге они были реорганизованны? Оставлять как в старом? Но тогда куда вставлять добавленные свойства?.
По-моему, новый файл дожен быть примером во всем: если что-то поменяли местами, значит так лучше! П.э. берем за основу новый порядок (т.е. по честному перетосовываем старые ноды).
То же касается и комментариев - в новом конфиге коммент может быть исправленным, п.э. комментарии обновляются всегда (для "внутренних пометок" остается лозейка - инлайн комменты). Родилось такое, вроде бы логичное, правило из простого примера:
# Очень большой
# Заголовок
# Коммент
prop1: val
prop2: val
Если в новом конфиге свойства переставлены, а коментарии бы не обновлялись то вся шапка уехала бы в комент к нижнему свойству (поскольку комент это все что находится над свойством). И вот только подмена комментов и выручает в этом случае (возвращая заголовок на место, в шапку файла).
Со скалярными списками все просто - это значение а значения мы не трогаем (т.е. оно просто переезжает со старого конфига, без перестановок):
list:
- 1
- 2
В случае объектных списков встает две проблемы:
networks:
- name: TCP
prop: 1
- name: UDP
prop: 2
Кроме того, я не знаю контр-примеров когда бы такое поведение было не верным.
Именно тут вылазит самая интересная проблема: а как понять какой элемент нового списка соотносится со старым? Порядок элементов может измениться, и вообще элемент может быть удален в новом конфиге.
Понятно что если у нового и старого элемента одно и то-же свойство иммет разные значения то естественно это теперь разнае элементы (как раз этот момент, в теории, и отсеит возможные исключительные случаи когда списки персонализируется и не предполагают обновления; хотя может сыграть и в обратную сторону).
Ну а дальше остается только считать количество совпавших значений (учитывая все поддерево элемента) - у кого больше всего совпадений, тот и референсный элемент. Причем если находится больше одного элемента с тем же количеством совпадений, считаем что референс не найден - обновления элемента не будет.
Например, для элемента a:1 в новом списке нет однозначного совпадения:
list:
- a: 1
b: 2
- a: 1
b: 3
Оба элемента подходят (остальные новые свойства не важны), а значит нужный элемент не найден.
А что если свойтво содержит лист? Для скалярного листа просто игнорируем. Например, если в новом конфиге:
list:
- a: 1
b:
- 1
- 2
- a: 2
b:
- 3
- 4
А оригинальный элемент был:
list:
- a: 1
b:
- 8
- 9
То первый элемент нового конфига считаем "совпавшим" (игнарируя листы).
Обоснования такомму подходу, если честно, нет. Просто на уровне интуиции показалось так правильнее. Вполне возможно что в скором времени всплывет контрпример и придется переделывать.
Для объектного списка волевым решением выбрано правило: должен совасть хоть один элемент. А совпасть это как? А это точно так же как описано выше (inception).
Даже по описанию видно насколько использваны вольные допущения, но как можно еще угадать? Практика покажет насколько это все было правильно.Я сколько мог примеров напридумывал (эта часть переписывалась несколько раз).
Например, в примере ниже level.oneи network[0] удалят:
level:
one: 1 # del
network:
- name: TCP # del
- name: UDP
Таким образом решается и проблема переопределения значения: просто удаляем старое и мержер вставит значение из нового конфига.
То же с листами: нужно обновить - удаляем старый, новый лист целиком его заменит.
Конечно это не покрывает все возможные случаи, но как наиболее сбалансированное должно подойти.
# айяй! нет пробела!
prop:value
И вот если бы я по честному писал парсер, то он раздулся бы в N раз, только благодаря валидации синтаксиса (не зря умные люди пугали).
Да и в любом случае, молодой парсер неизбежно содержит баги (сколько бы я его не вылизывал), чисто из-за малой базы простестированных ситуаций (как я, надеюсь, показал выше с YAML'ом непредвиденных ситуаций возникает много). И потому я решил считерить: взять надежный и проверенный временем парсер (snakeyaml) и валидировать им все файлики перед основным парсером.
Таким образом мой парсер всегда работает только с валидным YAML синтаксисом и может "не отвлекаться" на непредвиденные случаи.
Но этого мало - можно же проверить что эталонный и мой парсеры "видят" одно и то же дерево, тем самым сразу честно предупреждая о своих багах. Для этого пришлось сконвертировать дерево snakeyaml в модель совместимую с моей, зато теперь все что я не поддержал из YAML спеки легко вылезет наружу еще на стадии чтения файла.
Выше я упоминал что для сопоставления объектных списков используются значения свойств, при этом, парсер значениям уделяет мало внимания (важно сохранить как записано а не что). Поэтому при сравнении деревьев, точные значения из модели snakayaml проставляются в модель комментов, увеличивая точность сравнения списков.
Результат мержа так же читается snakeyaml'ом чтобы убедиться в корректности получившегося файла. Ну и раз точные деревья ДО и ПОСЛЕ уже подготовлены, полученное дерево валидируется на корректность: должно содержать все старое и все новое (тут сильно пригодился примитивный "YAML path" добавленный для удаления).
Нет, технически это можно было сделать: имея дерево нового файла не сложно в текущем файле узнать в коменте закоментированное свойство по контексту (без дерева-референса нельзя, иначе слишком просто "понапридумывать" свойств).
Но вот хорошего примера зачем такое могло бы пригодиться найти не удалось - ну и усложнение пошло под ножь.
Так появился вот такой репорт:
Configuration: /var/somewhere/config.yml (185 bytes, 23 lines)
Updated from source of 497 bytes, 25 lines
Resulted in 351 bytes, 25 lines
Added from new file:
prop/three 7 | three: 3 # new property
lists/obj[0]/three 20 | three: 3 # new value
Тут, кстати, интересный момент: почему в "YAML path" вместо точек разделителем идет / ? Да просто точка может запросто быть в именни свойства (например, te.st вполне допустимое имя - можете проверить, я не верил пока сам не убедился). И то что при удалении пути можно передавать с точкой просто упращение для пользователей (иначе будут "детские" ошибки, сам попадался).
В модели деревьев toString выдает техническую структуру дерева: ох как же без этого было тяжко дебажить. Зато теперь в дебагере сразу видишь все дерево и все понятно (да еще и в тестах валидировать модель через тустринг сильно удобнее). Ну и, конечно, как приятно когда отдельные ноды в дебаггере сразу "говорят" о себе все что нужно.
В валидационные ексепшены врендерены куски сравниваемых поддеревьев:
Comments parser validation problem on line 0: 1 child nodes found but should be at least 2 (this is a parser bug, please report it!)
Comments parser subtree: Structure parser subtree:
2| one: 2| one:
3| sub: s 3| sub: s
4| two: 2
(рядом, для наглядности) - не передать сколько времени это сэкономило при отладке (и надеюсь еще сэкономит в дальнейшем).
Жаль что такие полезные штуки почти всегда не пишутся сразу, а появляются лишь в условиях крайней необходимости.
Главное, в итоге я получил что хотел. Если стало инстересно посмотреть детальнее, то добро пожаловать на гитхаб.
habr.com
Естественно, что руки сами тянутся автоматизировать такое безобразие, но гугл быстро дал понять что не я один мечтаю о хорошем, только вот заветного оазиса пока никто не нашел. Нет, смержить два YAML файлика задача не трудная, но только если готов пожертвовать комментами (что для многих, как и для меня, недопустимо).
Как вы уже могли догадаться, тулзу я в итоге написал свою (java). Но рассказать я хочу не о том что она умеет, а о том что было после "да что я сам не сделаю что ли...".
Кода не будет, просто описание того с чем пришлось иметь дело и что в итоге пришлось сделать (что гораздо интереснее скучных циклов). Заранее извиняюсь за обилие англицизмов.
Начало
Для начала забавное наблюдение. Все разговоры в интернете про YAML парсеры начинаются с того какая спека сложная и как нетривиально написать YAML парсер (и это, конечно же, правда). А ведь понятно что для сохранения комментов свой парсер писать таки придется. И было не так легко перейти от мысли "куда ты лезешь, закопаешься!" к мысли "да мне нужен то лишь кусочек спеки, ничего страшного". Еще одна иллюстрация того что "все преграды в нашей голове".Минимальный парсер, для случая одного дерева в файле (без ссылок) пишется за один присест. А вот финальная модель для него сложилась не сразу.
Парсинг
Очевидно что для построения дерева главное вычленить имя свойства и его отступ.Правило для комментов тоже родилось сразу: "все что выше свойства это его коммент". Ну идеально же, так можно элементарно воссоздать файл 1-в-1 (а учитывая что чаще в апдейтах конфигов свойства добавляются без перемешивания остального, так вообще идеально). Для примера:
# Это все
# коммент для prop
prop:
# Это коммент для sub (включая пустую строку сверху)
sub: 1
# А это коммент для sub2 (отступ не важен)
sub2: 2
Еще одной важной вехой был принцип: одна нода (модели) - одна строчка файла (ну плюс строки коммента сверху конечно). Это и просто для понимания (при дебаге) и крайне удобно для записи модели обратно в файл.
Значение свойства само по себе не важно: для мержа достаточно имени. Поэтому можно принять за значение все что дальше двоеточия. Так и оригинальное форматирование сохраняется и инлайн комменты остаются.
prop: val # inline comment
Мультилайн
Первый раз YAML кольнул многострочными значениями: вы знали сколько опций настройки мультилайна в YAML? Я нет, но, тем не менее, эту часть пришлось честно реализовывать.multiline: some very
very very # с крмментарием
long value
Собсвенно, мультилайны определили вид value для нод как List<String>. По большому счету, главной проблемой было лишь определение где мультилайн заканчивается: значение сохраняется 1-в-1 (для того чтобы можно было его записать обратно без изменений), но вот отделить его от нижеследующего коммента крайне важно.
Списки
Список может быть скалярным:list:
- one
- two
Тут принцип одна строчка файла - одна нода ложиться идеально.
А может содержать объекты:
list:
- one: 1
two: 2
И вот тут то правило "одна нода - одна строчка" осеклось. Нет, я честно уперся рогом и долго пытался его придерживаться - получилось мягко говоря не очень: one: 1 был рутовой нодой (обозначающей объект списка), а все что дальше его детьми.
Пример ниже окончательно зарубил такой подход:
list:
- one: 1
sub: s
two: 2
(sub и two сливались в один список)
Пришлось вводить группирующую ноду (и сразу дышать стало легче). Так же это очень пригодилось когда вспомнил что листы могут записываться и так (spring boot любит такое написание):
list:
-
one: 1
two: 2
Естественно, большенство этих мутаций модели повылезали на этапе отладки мержера, но о нем отдельно.
Мержер
Казалось бы, есть два дерева - проще простого пробежаться да смержить модельки. Но, как всегда, не все так просто.Во-первых, могут измениться отступы:
Было:
level:
one: 1
Стало:
level:
one: 1
two: 2
Если мержить "в лоб" будет не валидный YAML:
level:
one: 1
two: 2
Значит нужно всегда переформатировать старые ноды согласно новым отступам (неважно в какую сторону). Причем крайне важно сдвигать все поддерево, а то можно порушить листы или мультилайны (которые очень завязаны на оступы). В рамках свойтва обязательно должны "съезжать" коммент и значение. Например, если сдвинуть только свойство здесь:
prop:
# комментарий
multiline: long long
long value
Получится некрасивый коммент и невалидное значение (ошибка синтаксиса):
prop:
# комментарий
multiline: long long
long value
Дальше - порядок свойств. Что если в новом конфиге они были реорганизованны? Оставлять как в старом? Но тогда куда вставлять добавленные свойства?.
По-моему, новый файл дожен быть примером во всем: если что-то поменяли местами, значит так лучше! П.э. берем за основу новый порядок (т.е. по честному перетосовываем старые ноды).
То же касается и комментариев - в новом конфиге коммент может быть исправленным, п.э. комментарии обновляются всегда (для "внутренних пометок" остается лозейка - инлайн комменты). Родилось такое, вроде бы логичное, правило из простого примера:
# Очень большой
# Заголовок
# Коммент
prop1: val
prop2: val
Если в новом конфиге свойства переставлены, а коментарии бы не обновлялись то вся шапка уехала бы в комент к нижнему свойству (поскольку комент это все что находится над свойством). И вот только подмена комментов и выручает в этом случае (возвращая заголовок на место, в шапку файла).
И снова списки
Как вы наверно уже догадались, списки я "люблю" больше всего. Кто бы мог подумать что это будет самой сложной частью.Со скалярными списками все просто - это значение а значения мы не трогаем (т.е. оно просто переезжает со старого конфига, без перестановок):
list:
- 1
- 2
В случае объектных списков встает две проблемы:
- Во-первых, может смениться стиль записи объекта с "начинаем после дэша" на "начинаем с новой строки после дэша" (или наоборот). Но это не сложно поддержать (буквально на уровне свойства модели).
- Во-вторых, нужно добавлять новые свойства в объекты списка.
networks:
- name: TCP
prop: 1
- name: UDP
prop: 2
Кроме того, я не знаю контр-примеров когда бы такое поведение было не верным.
Именно тут вылазит самая интересная проблема: а как понять какой элемент нового списка соотносится со старым? Порядок элементов может измениться, и вообще элемент может быть удален в новом конфиге.
Понятно что если у нового и старого элемента одно и то-же свойство иммет разные значения то естественно это теперь разнае элементы (как раз этот момент, в теории, и отсеит возможные исключительные случаи когда списки персонализируется и не предполагают обновления; хотя может сыграть и в обратную сторону).
Ну а дальше остается только считать количество совпавших значений (учитывая все поддерево элемента) - у кого больше всего совпадений, тот и референсный элемент. Причем если находится больше одного элемента с тем же количеством совпадений, считаем что референс не найден - обновления элемента не будет.
Например, для элемента a:1 в новом списке нет однозначного совпадения:
list:
- a: 1
b: 2
- a: 1
b: 3
Оба элемента подходят (остальные новые свойства не важны), а значит нужный элемент не найден.
А что если свойтво содержит лист? Для скалярного листа просто игнорируем. Например, если в новом конфиге:
list:
- a: 1
b:
- 1
- 2
- a: 2
b:
- 3
- 4
А оригинальный элемент был:
list:
- a: 1
b:
- 8
- 9
То первый элемент нового конфига считаем "совпавшим" (игнарируя листы).
Обоснования такомму подходу, если честно, нет. Просто на уровне интуиции показалось так правильнее. Вполне возможно что в скором времени всплывет контрпример и придется переделывать.
Для объектного списка волевым решением выбрано правило: должен совасть хоть один элемент. А совпасть это как? А это точно так же как описано выше (inception).
Даже по описанию видно насколько использваны вольные допущения, но как можно еще угадать? Практика покажет насколько это все было правильно.Я сколько мог примеров напридумывал (эта часть переписывалась несколько раз).
Удаление
Выше все было про добавление нового, но свойства могут и удаляться. Автоматизировать такое никак нельзя (пойди разберись потом что он там навыкашивал), поэтому пришлось вводить простейший "YAML path" чтобы можно было удалять как "листики" так и целые поддеревья передавая при запуске список путей для удаления.Например, в примере ниже level.oneи network[0] удалят:
level:
one: 1 # del
network:
- name: TCP # del
- name: UDP
Таким образом решается и проблема переопределения значения: просто удаляем старое и мержер вставит значение из нового конфига.
То же с листами: нужно обновить - удаляем старый, новый лист целиком его заменит.
Конечно это не покрывает все возможные случаи, но как наиболее сбалансированное должно подойти.
Надежность
Как все знают YAML крайне коварная штука - проще простого сделать что-то "не так". Например, мое любимое:# айяй! нет пробела!
prop:value
И вот если бы я по честному писал парсер, то он раздулся бы в N раз, только благодаря валидации синтаксиса (не зря умные люди пугали).
Да и в любом случае, молодой парсер неизбежно содержит баги (сколько бы я его не вылизывал), чисто из-за малой базы простестированных ситуаций (как я, надеюсь, показал выше с YAML'ом непредвиденных ситуаций возникает много). И потому я решил считерить: взять надежный и проверенный временем парсер (snakeyaml) и валидировать им все файлики перед основным парсером.
Таким образом мой парсер всегда работает только с валидным YAML синтаксисом и может "не отвлекаться" на непредвиденные случаи.
Но этого мало - можно же проверить что эталонный и мой парсеры "видят" одно и то же дерево, тем самым сразу честно предупреждая о своих багах. Для этого пришлось сконвертировать дерево snakeyaml в модель совместимую с моей, зато теперь все что я не поддержал из YAML спеки легко вылезет наружу еще на стадии чтения файла.
Выше я упоминал что для сопоставления объектных списков используются значения свойств, при этом, парсер значениям уделяет мало внимания (важно сохранить как записано а не что). Поэтому при сравнении деревьев, точные значения из модели snakayaml проставляются в модель комментов, увеличивая точность сравнения списков.
Результат мержа так же читается snakeyaml'ом чтобы убедиться в корректности получившегося файла. Ну и раз точные деревья ДО и ПОСЛЕ уже подготовлены, полученное дерево валидируется на корректность: должно содержать все старое и все новое (тут сильно пригодился примитивный "YAML path" добавленный для удаления).
Не все полезно
Долгое время была идея находить закоментированные свойства чтобы не добавлять дубликаты при мерже. Но в конце от нее отказался.Нет, технически это можно было сделать: имея дерево нового файла не сложно в текущем файле узнать в коменте закоментированное свойство по контексту (без дерева-референса нельзя, иначе слишком просто "понапридумывать" свойств).
Но вот хорошего примера зачем такое могло бы пригодиться найти не удалось - ну и усложнение пошло под ножь.
Репорт
Необходимость репорта всплыла сразу после первого же релиза: очень оказалось неприятно смотреть на радостное "я все сделал!" с немым вопросом "а что ты сделал с моим конфигом?"Так появился вот такой репорт:
Configuration: /var/somewhere/config.yml (185 bytes, 23 lines)
Updated from source of 497 bytes, 25 lines
Resulted in 351 bytes, 25 lines
Added from new file:
prop/three 7 | three: 3 # new property
lists/obj[0]/three 20 | three: 3 # new value
Тут, кстати, интересный момент: почему в "YAML path" вместо точек разделителем идет / ? Да просто точка может запросто быть в именни свойства (например, te.st вполне допустимое имя - можете проверить, я не верил пока сам не убедился). И то что при удалении пути можно передавать с точкой просто упращение для пользователей (иначе будут "детские" ошибки, сам попадался).
Отладка
Здесь хотелось бы вспомнить знаменитую цитату: "лучше день потерять, потом за 5 минут долететь". В который раз убеждаюсь что нет ничего лучше toString, написанного "для себя".В модели деревьев toString выдает техническую структуру дерева: ох как же без этого было тяжко дебажить. Зато теперь в дебагере сразу видишь все дерево и все понятно (да еще и в тестах валидировать модель через тустринг сильно удобнее). Ну и, конечно, как приятно когда отдельные ноды в дебаггере сразу "говорят" о себе все что нужно.
В валидационные ексепшены врендерены куски сравниваемых поддеревьев:
Comments parser validation problem on line 0: 1 child nodes found but should be at least 2 (this is a parser bug, please report it!)
Comments parser subtree: Structure parser subtree:
2| one: 2| one:
3| sub: s 3| sub: s
4| two: 2
(рядом, для наглядности) - не передать сколько времени это сэкономило при отладке (и надеюсь еще сэкономит в дальнейшем).
Жаль что такие полезные штуки почти всегда не пишутся сразу, а появляются лишь в условиях крайней необходимости.
Заключение
Вот так вот простая задачка "на пару вечеров", обрастала деталями и растянулась на пару месяцев. Я не стал тут затрагивать переменных, бэкапы, добавления CLI, сконцентрировавшись на интересном, но это все конечно тоже отъело свою "часть пирога".Главное, в итоге я получил что хотел. Если стало инстересно посмотреть детальнее, то добро пожаловать на гитхаб.
Миграция YAML конфигов или история одного парсера
Есть счастливые люди, которые могут себе позволить просто перезаписывать YAML конфиги в продакшене. Мне же повезло меньше - инсталляции у меня специфичные и конфиги часто настраиваются "под себя". К...
habr.com