Сеанс и соглашения A4

Как пишутся имена. В A4 три разных соглашения, и путать их нельзя. Имена команд — через дефис или одним словом: save-checkpoint, print-window, model, mutate; подчёркивания в именах команд нет ни одного. Имена полей — наоборот, через подчёркивание: document_id, paragraph_index, operation_kind, expected_revision. А значения полей, которые выбираются из списка, снова идут через дефис: insert-text, delete-line-break, merge-with-next. Ошибка в написании возвращает отказ, который читается как «команда не поддержана», хотя дело в одном знаке.

Для сравнения: в F1 поля пишутся слитно — subsetId, sheetKey, — и подчёркивания там не будет. Встраивая оба продукта, имя из одного в другом не ищите.

В чём измеряются размеры. Единицы две, и по имени поля видно, какая. Поля, кончающиеся на _twips, — в твипах: это единица разметки Word, одна тысяча четыреста сороковая доля дюйма. Дюйм — 1440 твипов, сантиметр — примерно 567, стандартное поле страницы в 2,54 см как раз и есть 1440. Поля, кончающиеся на _milli_px, — в тысячных долях пикселя: 96000 значит 96 px, а не девяносто шесть тысяч. Первое досталось от формата документа, второе — от экрана, и смешивать их нельзя.

Корреляция. Поле id необязательно и принимает любое значение JSON — строку или число. Ядро возвращает его без изменений, поэтому по нему ответ сопоставляется с запросом; в ответе поле есть всегда и равно null, если запрос его не нёс.

Порядок. Сессия хранит состояние между командами. Команда, которой нужен открытый документ, до open отказывает с текстом no document is open in this session.

Правка. Для mutate обязательны operation_kind и paragraph_index — у остальных полей есть значения по умолчанию. Нумерация абзацев с нуля. Виды правки перечислены в Объектах запросов и ответов.

Несохранённые изменения. Признак dirty означает, что текущая модель отличается от последнего сохранённого состояния, а не что документ испорчен.

Завершение. Ответ на shutdown содержит shutdown: true и не содержит ни cmd, ни elapsed_ms, ни result.

Время ответа. Таймаута в сеансе нет: ответ приходит, когда команда обработана. Ограничение по времени задаёт клиент. Единственный таймаут на стороне A4 — пять секунд на чтение HTTP-запроса в Surface Host.

Сохранение. Файл публикуется атомарно: запись идёт во временный файл рядом с целевым, содержимое доводится до диска, и только потом он заменяет цель. Оборванная запись не оставляет половинчатый DOCX — см. Жизненный цикл документа. Команда save-checkpoint вдобавок сверяет файл с тем состоянием, которое передали в expected_hash, и отказывает, если его изменили снаружи.

Формат сообщений и коды отказов — в Транспорте, перечень команд — в Session Protocol.