непокрытые секции доставки видны в статусе разбора
- половина потока (50 доставок из 104) не несёт metrics вовсе и до сих пор числилась parsed: ретеншен, поверив статусу, срезал бы тела stateOfMind, которых в экспорте Apple нет - разбор перечисляет верхнеуровневые ключи data, непокрытые проглатываются декодированием: тело 40 МиБ из непокрытой секции удерживает 0 МиБ - статус partial и колонка delivery.uncovered_sections; миграция переводит прежние parsed в pending — им верить нельзя - витрина не изменилась: отпечаток совпал с прогоном до изменения
This commit is contained in:
@@ -0,0 +1,277 @@
|
||||
## Context
|
||||
|
||||
Тело доставки HAE — это `{"data": {…секции…}}`. Разбор сегодня знает ровно одну
|
||||
секцию, `metrics`; всё остальное (`workouts`, `stateOfMind`, `symptoms`, `ecg`,
|
||||
`cycleTracking`, `medications`, `heartRateNotifications`) проходит мимо молча, и
|
||||
доставка получает `parse_status=parsed` с нулём точек.
|
||||
|
||||
Замер на живом архиве (99 доставок, 17 МБ сжатыми) показал, чем это стоит:
|
||||
|
||||
| набор верхнеуровневых ключей `data` | доставок |
|
||||
|---|---|
|
||||
| `metrics` | 51 |
|
||||
| `workouts` | 24 |
|
||||
| `stateOfMind` | 24 |
|
||||
|
||||
Три наблюдения, каждое из которых влияет на решение:
|
||||
|
||||
1. **Половина потока — не `metrics`.** 48 доставок из 99 сейчас числятся
|
||||
разобранными, не будучи разобранными.
|
||||
2. **Секции не смешиваются.** Ни одна доставка не несла двух секций сразу —
|
||||
автоматизация HAE шлёт одну секцию за раз.
|
||||
3. **Пустых секций не бывает.** Все 99 значений непусты; HAE не отправляет
|
||||
пустой пакет вовсе (находка 18).
|
||||
|
||||
Ограничения, в которые обязано вписаться решение:
|
||||
|
||||
- Тела доходят до 42 МиБ. Стратегия декодирования — часть контракта, её
|
||||
сторожит `TestParseУдержаниеКучи`: удержано не больше четырёх тел.
|
||||
- Разбор — чистая функция от тела и заголовков, без обращений к хранилищу.
|
||||
- Данные о здоровье чувствительнее токенов: в логе допустимы имена ключей,
|
||||
но не содержимое секций.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Доставка, содержащая непокрытую разбором секцию, отличима от доставки,
|
||||
разобранной целиком, — и в учёте, и в логе.
|
||||
- Список непокрытых ключей сохранён рядом с доставкой: он же ответ на вопрос
|
||||
«что останется потерянным, если тело удалить».
|
||||
- Перечисление не удерживает содержимого секций и не ломает контракт удержания
|
||||
кучи.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Разбор самих секций (`workouts`, `stateOfMind` и прочие) — отдельные задачи.
|
||||
- Ретеншен сырого архива. Здесь готовится признак, на который он обопрётся.
|
||||
- Ключи **верхнего** уровня тела помимо `data`. Форма `{"data": …}` проверяется
|
||||
приёмом, других ключей в потоке не наблюдалось; перечислять их значило бы
|
||||
смешать в одном списке имена секций и мусор конверта.
|
||||
- Подбор доставок в статусе `pending` — задача `otvet-i-svyortka`.
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Перечисление — в том же проходе, что и разбор метрик
|
||||
|
||||
`decodeMetrics` превращается в `decodeEnvelope`: один `json.Decoder` идёт по
|
||||
верхнему уровню тела, доходит до объекта `data` и разбирает его члены по
|
||||
одному. Имя члена читается `Token()`, значение покрытого ключа декодируется на
|
||||
месте в существующую форму (`[]metricEnvelope` с точками как
|
||||
`json.RawMessage`), значение непокрытого — **проглатывается** декодированием в
|
||||
выбрасываемый `json.RawMessage`.
|
||||
|
||||
Это форма из `ExampleDecoder_Decode_stream` стандартной библиотеки: `Token()`
|
||||
для рамки объекта и имён, `Decode()` для значений. В `encoding/json/v2` та же
|
||||
операция названа прямо — `jsontext.Decoder.SkipValue`.
|
||||
|
||||
Альтернативы и чем плохи:
|
||||
|
||||
- **Пропуск ручным счётом глубины по `Token()`.** Выглядит дешевле — и
|
||||
измеримо хуже: делимитеры идут мимо сканера, поэтому ограничитель вложенности
|
||||
`encoding/json` (10 000 уровней) не работает, а стек токенов растёт как
|
||||
O(глубины). Измерено: тело 40 МиБ из вложенных скобок даёт пик кучи 488 МиБ
|
||||
(12 тел вместо контрактных четырёх), тогда как `Decode` отвергает его
|
||||
мгновенно. На настоящей секции 27 МиБ счёт глубины стоит 331 МиБ мусора и
|
||||
689 мс против 91 МиБ и 190 мс у `Decode`.
|
||||
- **Второй проход по телу.** Перечисление стало бы независимым от разбора, но
|
||||
42 МиБ прошли бы через токенизатор дважды — вся секция `metrics` во второй
|
||||
раз впустую.
|
||||
- **`Data map[string]json.RawMessage`.** Три строки кода, но `RawMessage`
|
||||
копирует байты **всех** секций и держит их до конца разбора. У проглатывания
|
||||
копия одна, живёт до следующего члена и удерживается ноль.
|
||||
- **Свой сканер по байтам тела.** Не нужно: `encoding/json` умеет всё нужное, а
|
||||
собственный сканер JSON — это экранирование строк, суррогатные пары и вечный
|
||||
источник расхождений.
|
||||
|
||||
Граница утверждения: речь о пике внутри `hae.Parse`. Приём отдельно держит свою
|
||||
копию `data` (`ingest.checkEnvelope`), и на пик процесса влияет она же —
|
||||
перечисление этого не меняет.
|
||||
|
||||
### 2. Непокрытый — значит не разобранный, а не «пустой»
|
||||
|
||||
Ключ попадает в список, если разбор его **не покрывает**, независимо от того,
|
||||
что внутри. Содержимое не удерживается — значит и о пустоте секции мы честно
|
||||
ничего не знаем.
|
||||
|
||||
Соблазн «пустую секцию не считать» существует: он снял бы шум, если бы HAE слал
|
||||
`"workouts": []` в каждой доставке. Замер говорит, что не слал ни разу.
|
||||
|
||||
Покрытая секция сегодня ровно одна — `metrics`. Покрытость выражена **функцией**
|
||||
рядом с разбором, а не изменяемой пакетной картой: разбор и перечисление ходят
|
||||
по одному источнику, состояние «секция разбирается, но числится непокрытой»
|
||||
невыразимо.
|
||||
|
||||
Список **канонизируется перед выдачей**: сортировка по имени и удаление
|
||||
повторов. Порядок ключей в JSON от HAE нестабилен (находка 30 и вся история
|
||||
канонизации содержимого), а значение уезжает в базу и сравнивается между
|
||||
доставками; список, зависящий от порядка на проводе, сравнивать нельзя.
|
||||
|
||||
### 3. Статус `partial` — исход разбора, а не третий вид отказа
|
||||
|
||||
```
|
||||
pending этим разбором ещё не смотрели
|
||||
parsed разобрано всё, что в теле было
|
||||
partial разобрано покрытое; в теле остались непокрытые секции
|
||||
failed разобрать не удалось, точек нет
|
||||
```
|
||||
|
||||
Источник истины — **список**; статус производен от него и от факта отказа:
|
||||
|
||||
```
|
||||
failed ← разбор вернул ошибку (сильнее всего)
|
||||
partial ← список непуст
|
||||
parsed ← иначе
|
||||
```
|
||||
|
||||
Приоритет назван явно, потому что иначе два будущих читателя (ретеншен,
|
||||
`/stats`) разойдутся: один спросит `parse_status`, другой —
|
||||
`uncovered_sections != '[]'`. Спрашивать полагается статус; список отвечает на
|
||||
вопрос «что именно осталось».
|
||||
|
||||
Список сохраняется и при отказе, если разбор успел его собрать: доставка
|
||||
`metrics` + `stateOfMind`, у которой не определился слой, обязана остаться
|
||||
записью о том, что в теле есть невосстановимая секция. Поэтому `failed` с
|
||||
непустым списком — законное состояние, а не противоречие.
|
||||
|
||||
`CHECK` на колонке нет (конвенция: допустимые значения держит код), поэтому
|
||||
новый статус миграции сам по себе не требует.
|
||||
|
||||
### 4. Список непокрытых ключей хранится JSON-массивом
|
||||
|
||||
Колонка `delivery.uncovered_sections TEXT NOT NULL DEFAULT '[]'`, значение —
|
||||
JSON-массив имён (`["stateOfMind"]`), пустой список — `[]`.
|
||||
|
||||
Почему массивом, а не строкой с разделителем: имя ключа приходит из чужого
|
||||
тела и может содержать что угодно, включая пробел и запятую. JSON снимает
|
||||
вопрос разделителя, согласуется с колонкой `headers` и читается из SQLite через
|
||||
`json_each`, если ретеншену это понадобится.
|
||||
|
||||
Ровно одно представление пустоты — `[]`. `nil`-срез в Go сериализуется как
|
||||
`null`, поэтому нормализация делается на границе `store` тем же приёмом, каким
|
||||
там уже нормализуются `headers` (пустое → `{}`).
|
||||
|
||||
Запись **замещает** прежнее значение целиком, включая замещение пустым. Это
|
||||
отличается от `derived_layer`, где пустая строка означает «не трогать»:
|
||||
у слоя пустота — отсутствие знания, у списка — знание об отсутствии.
|
||||
|
||||
### 5. Границы на список: 32 ключа, 64 байта на имя, и обе обрезки видны
|
||||
|
||||
Тело контролирует отправитель целиком. Без границ тело из ста тысяч
|
||||
однобуквенных ключей превращается в одну строку в базе и одну строку в логе
|
||||
того же порядка. Поэтому:
|
||||
|
||||
- не больше 32 имён; число отброшенных сверх лимита идёт **счётчиком**
|
||||
(`UncoveredDropped`) в исход разбора и атрибутом лога — иначе «ровно 32
|
||||
секции» неотличимо от «пришло пятьсот», а список ровно для того и заведён,
|
||||
чтобы отвечать на вопрос о полноте;
|
||||
- имя длиннее 64 байт обрезается по границе рун, к обрезанному имени
|
||||
приписывается маркер `…`; маркер **сверх** предела, а не внутри него;
|
||||
- граница считается по байтам **декодированного** имени: `Token()` отдаёт имя
|
||||
уже после разбора escape-последовательностей.
|
||||
|
||||
Числа выбраны с запасом: секций у HAE восемь, самое длинное имя —
|
||||
`heartRateNotifications` (22 байта). Обрезка не инъективна (два длинных ключа
|
||||
могут дать одно имя), поэтому она и помечается — обрезанное имя сравнению со
|
||||
словарём известных секций не подлежит.
|
||||
|
||||
Срабатывание любой из границ — событие уровня `WARN`: это не частичный разбор,
|
||||
а тело, не похожее на HAE.
|
||||
|
||||
### 6. Уровень лога от одной лишь частичности не растёт
|
||||
|
||||
Непокрытые ключи добавляются атрибутом `uncovered` в единственный логирующий
|
||||
чекпоинт свёртки — там, где уже живут `layer`, `sealed_hits` и прочие признаки.
|
||||
|
||||
`WARN` на самой частичности был бы неверен: `partial` — не отклонение, а
|
||||
установившееся состояние половины потока (48 доставок из 99). Постоянный `WARN`
|
||||
каждые пять минут обесценивает уровень ровно так же, как обесценило бы
|
||||
сравнение с заголовком `Default`. Момент появления **новой** секции — отдельная
|
||||
задача (`proverka-novyh-sekcij`), и она будет опираться на сохранённый список.
|
||||
|
||||
Имена идут структурным атрибутом (`[]string`), а не склейкой в строку: JSON-
|
||||
кодировщик `slog` экранирует управляющие символы, поэтому имя из чужого тела не
|
||||
разрывает построчный разбор логов. Содержимого секций в записи нет ни на каком
|
||||
уровне выше `DEBUG`.
|
||||
|
||||
### 7. Отказ разбора — всё или ничего, как и раньше
|
||||
|
||||
Разбор стал потоковым, и ошибка может встретиться **после** того, как `metrics`
|
||||
уже разобрана (обрезанное тело, мусор в следующем члене). Правило прежнее:
|
||||
`Parse` при ошибке точек не отдаёт, свёртка ничего не сливает и пишет `failed`.
|
||||
Иначе свёртка перестала бы быть детерминированной по журналу: часть точек
|
||||
оказалась бы в витрине под статусом, по которому доставку никто не подберёт.
|
||||
|
||||
Повтор ключа `metrics` (JSON это допускает) даёт **объединение** секций, а не
|
||||
победу последней: терять точки молча нельзя. Повтор непокрытого ключа даёт одно
|
||||
имя в списке — список канонизирован.
|
||||
|
||||
### 8. Строки, свёрнутые прежним кодом, переводятся в `pending`
|
||||
|
||||
Статус `parsed`, поставленный кодом, который частичного разбора не различал,
|
||||
ничего не доказывает: под ним лежат и полностью разобранные доставки, и
|
||||
`workouts`-доставки с нулём точек. Ретеншен, ради которого признак и заводится,
|
||||
поверил бы им и срезал тела.
|
||||
|
||||
Поэтому миграция переводит существующие `parsed` в `pending` — «этим разбором
|
||||
ещё не смотрели». Это консервативный статус: ретеншен не трогает `pending`
|
||||
никогда, а подбор `pending` (задача `otvet-i-svyortka`) пересвернёт доставки из
|
||||
архива. Свёртка идемпотентна, повторный прогон журнала состояния не меняет —
|
||||
проверено `task verify:archive`.
|
||||
|
||||
Рассматривался целевой перевод только строк с `points = 0` (те самые 48). Он
|
||||
опирается на наблюдение «секции не смешиваются», собранное за двое суток
|
||||
потока, — а ставить на такое наблюдение необратимое удаление тел значит
|
||||
повторять ошибку, ради которой задача и заведена.
|
||||
|
||||
Следствия, названные вслух:
|
||||
|
||||
- `pending` теперь означает «этим разбором ещё не смотрели», а не «тела ещё не
|
||||
касались». Док-комментарий константы и `docs/database.md` правятся тем же
|
||||
изменением.
|
||||
- `points` у переведённых строк остаётся прежним до пересвёртки: он производен
|
||||
от объектов витрины, которые никуда не делись.
|
||||
- Миграция **односторонняя по данным**: `Down` снимает колонку, но какие
|
||||
доставки были `parsed`, восстановить неоткуда. Цена нулевая — состояние
|
||||
пересобирается из архива, — но откат перестаёт быть операцией «вернулись и
|
||||
работаем»: до появления подбора `pending` строки останутся в этом статусе.
|
||||
- Порядок задач: пока `otvet-i-svyortka` не сделана, 99 доставок числятся
|
||||
`pending` и никем не подбираются. Приём и свёртка новых доставок при этом
|
||||
работают как раньше.
|
||||
|
||||
### 9. Правило для будущих задач: покрыли секцию — пересверните
|
||||
|
||||
Список — снимок покрытия **на момент свёртки**. Доставки, свёрнутые до того,
|
||||
как секция стала покрытой, останутся `partial` со старым списком, и ретеншен
|
||||
будет вечно щадить тела, которые уже не нужны.
|
||||
|
||||
Поэтому конвенция, вводимая этим изменением: задача, которая начинает разбирать
|
||||
секцию, тем же изменением переводит `partial`-строки с этим ключом в `pending`
|
||||
— тем же приёмом, что и миграция здесь. Ретеншену позволено смотреть на
|
||||
`partial` только при соблюдении этого правила.
|
||||
|
||||
### 10. Фикстура рукотворная — и это осознанно
|
||||
|
||||
Конвенция требует тестов на реальных пакетах, но здесь проверяется конверт, а
|
||||
не содержимое: секция не читается вовсе, поэтому реальность её содержимого
|
||||
ничего не доказывает. Реальный пакет `stateOfMind` под контроль версий не
|
||||
попадёт никогда — это измерения состояния разума, а санитайзер `fixtures.py`
|
||||
написан под метрики. Живой поток покрывается прогоном `task verify:archive`,
|
||||
который проходит по всем 99 доставкам архива.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **Проглатывание непокрытой секции копирует её байты** → копия одна, живёт до
|
||||
следующего члена, удерживается ноль; пик внутри `Parse` — тело плюс
|
||||
наибольшая непокрытая секция, то есть вдвое меньше контрактного предела.
|
||||
- **99 доставок разом станут `pending`** → до появления подбора `pending` они
|
||||
останутся в этом статусе. Данные не теряются: тела в архиве, объекты в
|
||||
витрине, а `pending` безопаснее ложного `parsed`.
|
||||
- **Обрезка длинного имени искажает его** → маркер делает обрезку видимой,
|
||||
счётчик отброшенных — неполноту списка; оба идут в лог `WARN`.
|
||||
- **`partial` — новое значение в колонке без `CHECK`** → значения держит код,
|
||||
как и для остальных статусов; тест на запись и чтение статуса закрывает
|
||||
опечатку.
|
||||
- **Регресс в переписанном пути к `metrics`** → сверка витрины, собранной из
|
||||
живого архива, со снимком, снятым до изменения: совпадение по объектам,
|
||||
точкам и метрикам, а не только сходимость нового кода с самим собой.
|
||||
Reference in New Issue
Block a user