healthlog/openspec/specs/points/spec.md

points Specification

Purpose

Ряд точек одной метрики за период — то, ради чего собирается витрина. Каталог отвечает «что у тебя есть», этот маршрут — «дай значения». Форма запроса и его разбор, правило выбора слоя, состав конверта и объявление измеренного рода вместе с границей окна измерения живут здесь; общие правила читающих маршрутов — в capability read-api.

Requirements

Requirement: Точки метрики за период отдаются одним запросом

Система SHALL отдавать значения одной метрики за запрошенный период по GET /api/v1/metrics/{name} с обязательными параметрами from и to, не требуя от потребителя доступа к файлу базы и не требуя второго запроса за смыслом отданных чисел.

Имя метрики берётся из пути ровно один раз декодированным и далее дословно: система его не нормализует и не сверяет со списком известных — имена приходят из тела доставки и хранилищу не принадлежат. Повторное декодирование MUST NOT происходить: имя, само содержащее процентную последовательность (a%41b), после второго декодирования становится именем другой метрики, и маршрут отвечает 200 с её данными. Имя, которое путём не выражается (пустое), маршрутом недостижимо; каталог такую метрику показывает, и это названная цена адресации именем в пути, а не молчание.

Маршрут закрыт токеном чтения тем же контуром, что и каталог, и MUST NOT перехватывать маршрут каталога GET /api/v1/metrics.

Scenario: Период запрошен

• GIVEN метрика, у которой в витрине есть объекты внутри периода
• WHEN потребитель запрашивает GET /api/v1/metrics/{name}?from=…&to=… с действующим токеном чтения
• THEN ответ 200 несёт значения этой метрики за этот период

Scenario: Каталог остаётся достижим

• WHEN потребитель запрашивает GET /api/v1/metrics
• THEN отвечает каталог, а не маршрут точек

Scenario: Имя метрики закодировано в пути

• GIVEN метрика, чьё имя содержит символ, требующий процентного кодирования
• WHEN потребитель запрашивает её точки, закодировав имя
• THEN отвечают точки этой метрики, а не пустой ряд

Scenario: Имя метрики само содержит процентную последовательность

• GIVEN метрики с именами a%41b и aAb в витрине
• WHEN потребитель запрашивает a%41b, закодировав имя
• THEN отвечают точки a%41b, а не точки aAb

Scenario: Токен чтения отсутствует

• WHEN запрос точек приходит без действующего токена чтения при непустом списке токенов чтения
• THEN ответ 401, и тело ответа собрано объявленным типом транспорта

Requirement: Конверт ответа объявляет слой, род свёртки, его применимость и границу окна измерения

Система SHALL сопровождать точки конвертом, в котором ВСЕГДА присутствуют поля metric, from, to, layer, bucket, aggregation и points, а объект aggregation MUST всегда нести поля style, applicable и last_hour. Поле, которому нечего сообщить, MUST уезжать как null и MUST NOT исчезать из ответа и MUST NOT подменяться нулевым значением своего типа.

Смысл полей:

• metric — имя метрики, как оно пришло путём после декодирования;
• from и to — фактически применённые границы периода, нормализованные к UTC в RFC 3339;
• layer — слой, из которого собран ряд;
• bucket — сетка свёртки; null, когда свёртки не было;
• aggregation.style — измеренный род метрики (cumulative / instant / unknown) тем же правилом и тем же окном, что у каталога;
• aggregation.applicable — применим ли объявленный род к отданному ряду;
• aggregation.last_hour — ярлык самого свежего часа окна измерения; null, когда окно пусто;
• points — ряд, пустой коллекцией [], а не null.

last_hour обязателен именно потому, что окно измерения считается в общих часах, а не в часах календаря: выключенная минутная автоматизация HAE останавливает пополнение общих часов, окно замирает и продолжает объявлять род. Без last_hour у клиента нет ни одного способа это увидеть.

Scenario: Свёртки не было

• WHEN маршрут отвечает на запрос без сетки
• THEN в ответе присутствуют metric, from, to, layer, bucket, aggregation со всеми тремя полями и points, причём bucket равен null

Scenario: Окно измерения замерло

• GIVEN метрика, чьи самые свежие общие часы старше конца запрошенного периода
• WHEN маршрут отвечает
• THEN aggregation.last_hour называет ярлык самого свежего общего часа, а не конец периода и не текущее время

Scenario: Окна измерения нет вовсе

• GIVEN метрика, у которой нет ни одного общего часа минутного и часового слоёв
• WHEN маршрут отвечает
• THEN aggregation.style равен "unknown", а aggregation.last_hour равен null

Requirement: Род, объявленный в ответе, едет вместе со своей применимостью к отданному ряду

Система SHALL объявлять aggregation.applicable равным false всегда, когда объявленный род нельзя применить к отданному ряду, и MUST считать неприменимым род cumulative на нижнем слое HAE (raw), род unknown и любой род при отсутствии выбранного слоя. Система MUST NOT досчитывать свёртку по неизмеренному роду и MUST NOT выражать неизвестность отсутствием поля.

Поле существует потому, что род — свойство метрики, а слой — свойство отданного ряда, и их сочетание бывает опасным: нижний слой HAE это интерполяция, а не сэмплы, и сумма по нему завышает втрое. Конверт, объявляющий cumulative рядом с рядом из raw и молчащий о неприменимости, приглашает потребителя сложить интерполяцию самостоятельно — система при этом не складывает ничего, а решение у потребителя уже принято по завышенному числу.

Scenario: Род метрики не измерен

• GIVEN метрика, у которой род агрегации не измерен
• WHEN потребитель запрашивает её точки за период
• THEN ответ 200 несёт точки как есть, aggregation.style равен "unknown", а aggregation.applicable равен false

Scenario: Накопительная метрика отдана нижним слоем

• GIVEN метрика с измеренным родом cumulative, ряд которой собран из слоя raw
• WHEN маршрут отвечает
• THEN aggregation.style равен "cumulative", а aggregation.applicable равен false

Scenario: Род применим

• GIVEN метрика с измеренным родом, ряд которой собран из слоя minute, hour или sample
• WHEN маршрут отвечает
• THEN aggregation.applicable равен true

Requirement: Слой выбирается по охвату точек внутри периода и не меняется внутри ответа

Система SHALL собирать ряд ровно из одного слоя и MUST NOT склеивать в одном ответе точки разных слоёв. При отсутствии параметра layer система SHALL брать слой с наибольшим охватом внутри запрошенного периода, а при равном охвате — самый мелкий слой в порядке sample, raw, minute, hour, day.

Охват меряется метками точек, а не часами объектов. Охват слоя есть длина пересечения отрезка [первая метка слоя, последняя метка слоя] с запрошенным периодом; слой с пустым пересечением из выбора MUST выбывать. Мера названа именно так потому, что объекты адресуются часом, а ряд отбирается точной меткой: на периоде короче часа множество «слоёв с объектами» и множество «слоёв с точками» расходятся, и слой, выбранный по часам, отдал бы пустой ряд при непустых данных соседнего слоя.

Охват сравнивается между слоями, а не с запрошенным периодом: границы данных законно короче запроса и законно имеют дыры внутри.

Заданный параметр layer отменяет правило целиком: система SHALL отдавать запрошенный разрез, в том числе пустым, и SHALL называть его в ответе.

Scenario: Мелкий слой охватывает меньше крупного

• GIVEN метрика, у которой внутри периода нижний слой покрывает несколько дней, а часовой — весь период
• WHEN потребитель запрашивает период без параметра layer
• THEN ряд собран из часового слоя, и layer называет его

Scenario: Охваты равны

• GIVEN метрика, у которой два слоя охватывают внутри периода одно и то же
• WHEN потребитель запрашивает период без параметра layer
• THEN ряд собран из более мелкого слоя

Scenario: Период короче часа

• GIVEN период внутри одного часа, в котором у крупного слоя есть объект без единой точки внутри периода, а у мелкого — точки внутри периода
• WHEN потребитель запрашивает период без параметра layer
• THEN ряд собран из мелкого слоя и не пуст

Scenario: Слой задан явно

• WHEN потребитель задаёт layer явно
• THEN ряд собран из этого слоя, даже если другой слой охватывает период шире, и layer в ответе равен запрошенному

Scenario: Имя слоя незнакомо

• WHEN параметр layer присутствует, а его значение не является одним из sample, raw, minute, hour, day
• THEN ответ 400, и умолчание молча не подставляется

Scenario: Значение слоя пусто

• WHEN параметр layer присутствует с пустым значением
• THEN ответ 400, а не автоматический выбор слоя

Requirement: Период задаётся явно и разбирается строго

Система SHALL требовать оба параметра from и to, SHALL принимать их только в формате RFC 3339 с явным смещением зоны и SHALL толковать период как полуинтервал [from, to). Отсутствующий параметр, неразбираемое значение, значение без явной зоны, from >= to и граница, чей год после приведения к UTC выходит за диапазон 1–9999, MUST давать 400 с человекочитаемым сообщением, которое MUST NOT содержать значений из запроса, и MUST NOT подменяться умолчанием.

Граница за пределами четырёхзначного года отвергается потому, что объекты адресуются строкой RFC 3339 и границы сравниваются лексикографически: 9999-12-31T23:00:00-07:00 становится 10000-01-01T06:00:00Z, который как строка меньше любой настоящей метки, — и запрос молча отдал бы пустой ряд при непустых данных.

Полуинтервал взят потому, что соседние окна обязаны склеиваться без двойного счёта граничной точки. Явная зона обязательна потому, что вопрос «в какой зоне считать сутки» в проекте открыт: принять голую дату значило бы выбрать зону за клиента молча.

Параметр bucket этой версией маршрута не поддержан: система SHALL отвечать 400 на его присутствие с любым значением и MUST NOT игнорировать его молча. Молчаливое игнорирование дало бы клиенту, попросившему суточную сетку, полный минутный ряд — зеркало того самого промаха, ради которого соседняя задача различает «указали сетку» как информацию и как защиту. Прочие незнакомые параметры запроса система игнорирует.

Scenario: Параметр периода отсутствует

• WHEN в запросе нет from или нет to
• THEN ответ 400, и период умолчанием не подставляется

Scenario: Метка времени без зоны

• WHEN значение from или to записано без явного смещения зоны
• THEN ответ 400

Scenario: Границы периода вывернуты

• WHEN from не раньше to
• THEN ответ 400

Scenario: Граница выходит за четырёхзначный год

• WHEN граница периода после приведения к UTC попадает в год за пределами диапазона 1–9999
• THEN ответ 400, а не 200 с пустым рядом

Scenario: Запрошена сетка свёртки

• WHEN в запросе присутствует параметр bucket
• THEN ответ 400, называющий, что свёртка ещё не поддержана

Scenario: Точка стоит ровно на границе

• GIVEN точки с метками ровно в from и ровно в to
• WHEN маршрут отвечает
• THEN точка на from в ответе есть, а точка на to — нет

Requirement: Значение точки уезжает дословно, нормализовано только время

Система SHALL отдавать каждую точку объектом {ts, ts_end, tz_offset, units, values}, где values MUST быть содержимым точки ровно в том виде, в каком его сохранило хранилище, без переименования полей, пересчёта единиц, отбрасывания незнакомого и без экранирования. ts и ts_end MUST быть нормализованными к UTC метками начала и конца координаты точки; у точки-измерения ts_end равен ts. tz_offset и units MUST принадлежать самой точке: смещение исходной зоны — её собственное, единицы — того объекта, из которого точка прочитана.

Точки MUST идти по возрастанию (ts, ts_end). Порядок этим определён однозначно: пара (начало, конец) внутри одного слоя одной метрики есть ключ идентичности, и двух точек с равной парой в витрине не существует.

Принадлежность точки периоду определяется её началом: точка-интервал, начавшаяся раньше from, в ответ не входит, даже если её конец лежит внутри периода. Правило то же, каким час объекта берётся по началу точки; цена названа вслух — запрос «сон за ночь с полуночи» не увидит эпизод, начавшийся до неё.

ts_end присутствует потому, что идентичность точки — интервал, а не метка: под одной меткой лежит до трёх записей сна, и конверт с одним ts предлагал бы клиенту различать их, разбирая дословное содержимое.

Scenario: Точка-интервал

• GIVEN точка, у которой конец координаты отличается от начала
• WHEN маршрут отвечает
• THEN ts_end отличается от ts и называет конец координаты

Scenario: Содержимое не переписывается

• WHEN точка уезжает клиенту
• THEN values побайтово совпадает с сохранённым содержимым точки

Scenario: Содержимое несёт символы, которые сериализатор склонен экранировать

• GIVEN точка, чьё содержимое несёт &, < или >
• WHEN маршрут отвечает
• THEN эти символы уезжают как есть, а не escape-последовательностями

Requirement: Пустота периода — успех, а не отсутствие ресурса

Система SHALL отвечать 200 на запрос метрики, у которой нет данных в запрошенном периоде, и MUST отдавать points пустым списком. Система MUST NOT отвечать 404 по признаку «нет данных».

layer равен null только тогда, когда слой выбирала система и выбирать было не из чего. Заданный клиентом layer уезжает в ответе всегда, даже когда ряд пуст: иначе клиент, спросивший разрез поимённо, не отличил бы «этого разреза за период нет» от «маршрут проигнорировал параметр».

Различать опечатку в имени метрики и честную пустоту — работа каталога: список имён маршруту точек не принадлежит.

Scenario: Данных за период нет и слой не задан

• WHEN у метрики нет ни одной точки внутри периода и параметр layer не задан
• THEN ответ 200, points равен [], layer равен null

Scenario: Данных за период нет, а слой задан

• WHEN у метрики нет точек запрошенного слоя внутри периода
• THEN ответ 200, points равен [], layer равен запрошенному

Scenario: Имени метрики в витрине нет вовсе

• WHEN запрошено имя метрики, которого в витрине нет
• THEN ответ 200 с пустым points, а не 404

Requirement: Ответ снимается одним снимком витрины

Система SHALL читать охваты слоёв, точки выбранного слоя и объекты окна измерения в одной транзакции чтения. Смесь «слой выбран до коммита свёртки, точки прочитаны после» и «род измерен на третьем состоянии» дала бы ответ, внутренне противоречивый и неотличимый от обычного свежего; пара проб версии такой ответ обнаруживает, но не предотвращает — она снимает метку, а тело всё равно уезжает.

Scenario: Свёртка коммитит во время чтения

• WHEN фоновая свёртка коммитит в витрину между выбором слоя и чтением точек
• THEN ответ собран из одного снимка витрины, а не из двух состояний

Requirement: Метка ответа включает канонизированную форму запроса и горизонт измерения

Система SHALL помечать ответ меткой, область действия которой MUST быть функцией канонизированной формы запроса — имени метрики, границ периода и слоя — и которая MUST включать горизонт измерения, огрублённый до часа, наравне с версией витрины. При невозможности подписать ответ система SHALL отдавать его без метки, а не отказом.

Область MUST быть ограничена по длине и не выносить значения запроса наружу. Имя метрики приходит из чужого тела дословно и ничем не ограничено: положенное в метку как есть, оно даёт заголовок в тысячи байт, а кавычка внутри имени по HTTP кончает метку — разбор обрежет её там, и условный запрос по такой метрике не сработает никогда. Тот же вход в лог уезжает обрезанным, и у метки предел обязан быть по той же причине.

Канонизация границ MUST сохранять точность, по которой отбираются точки: два запроса, различающиеся долей секунды, дают разные ряды, и одна метка на них подтвердила бы неизменность чужого набора данных.

Горизонт входит в метку по той же причине, по какой он входит в метку каталога: род объявляется по окну, ограниченному сверху текущее время + запас, и метка из будущего, лежащая в витрине, въезжает в окно без единого коммита, меняя aggregation.style и last_hour. Метка без горизонта подтвердила бы неизменность ответа, в котором род уже перевернулся. Форма запроса входит в область действия потому, что ответ этого маршрута есть функция параметров: метка без них однажды подтвердила бы неизменность чужого набора данных. Род и метка MUST сниматься с одного горизонта.

Цена названа: один полный ответ в час на потребителя при неизменившейся витрине.

Scenario: Запросы различаются параметром

• WHEN два запроса при одном состоянии витрины различаются метрикой, границей периода или слоем
• THEN метки их ответов различны

Scenario: Запросы различаются только формой записи

• WHEN два запроса при одном состоянии витрины задают одно и то же разной записью смещения зоны
• THEN метки их ответов совпадают

Scenario: Границы различаются долей секунды

• WHEN два запроса при одном состоянии витрины различаются границей периода на долю секунды и дают разные ряды
• THEN метки их ответов различны

Scenario: Имя метрики длинное или содержит кавычку

• WHEN запрошена метрика, чьё имя длиной в тысячи символов или содержит кавычку
• THEN метка ответа остаётся короткой и не содержит имени метрики

Scenario: Горизонт перешёл через час

• WHEN горизонт измерения перешёл через границу часа при неизменной версии витрины
• THEN метка ответа изменилась

Scenario: Витрина изменилась во время чтения

• WHEN пробы версии витрины разошлись
• THEN ответ уходит целиком и без метки

Requirement: Исход маршрута точек наблюдаем, а данные о здоровье в лог не уезжают

Система SHALL писать один логирующий чекпоинт исхода на доменной границе маршрута и MUST NOT доводить до записи лога значения точек, содержимое values и границы запроса; имя метрики MUST быть обрезано по тому же пределу, что у каталога. Отмена запроса клиентом и занятость базы MUST писаться уровнем DEBUG, а настоящий отказ хранилища — уровнем ERROR.

Предупреждения измерения — противоречащий род и данные, помеченные будущим, — остаются привилегией каталога: маршрут точек их MUST NOT повторять. Агент опрашивает по расписанию, и WARN на каждый опрос обесценил бы уровень ровно так же, как обесценила бы его строка на каждый 304.

Scenario: Клиент оборвал запрос

• WHEN потребитель обрывает запрос точек по своему тайм-ауту
• THEN запись об этом уходит уровнем DEBUG, а не ERROR

Scenario: Метрика с противоречащим родом запрошена многократно

• WHEN потребитель повторно запрашивает точки метрики, у которой род противоречив
• THEN маршрут точек предупреждений об этом не пишет

Scenario: Тело ответа оборвалось на середине

• WHEN запись тела ответа отказала после того, как код ответа уже отдан
• THEN отказ записи оставляет собственный чекпоинт и не проходит молча под видом успешного ответа