Транспорт и формат сообщений A4

Обмен строками JSON и через WebSocket, формат запроса и ответа, тексты отказов, таймауты и версии контрактов обмена.

JSONL stdio

# $CLI — путь к процессору внутри установленного приложения,
# он задан на странице «Установка и проверка»
"$CLI" serve
{
  "schema": "fastdoc.session-serve.v1",
  "stage_id": "D7",
  "session_kind": "jsonl-stdio-document-session-prototype",
  "supported_commands": [
    "apply-composition",
    "apply-text-transaction",
    "commit-snapshot",
    "commit-structural-snapshot",
    "compatibility-inspect",
    "compose",
    "model",
    "mutate",
    "open",
    "paginate",
    "ping",
    "print",
    "print-delta",
    "print-summary",
    "print-window",
    "redo",
    "report",
    "review",
    "save",
    "save-checkpoint",
    "set-selection",
    "shutdown",
    "simple-field-inventory",
    "squash-history",
    "status",
    "style",
    "track-revisions-state",
    "undo"
  ],
  "ready": true
}

WebSocket

"$CLI" serve --ws 0 [--token <token>]
{"schema":"fastdoc.session-ws-bootstrap.v1","transport":"websocket","host":"127.0.0.1","port":49152,"token":"<64 hex>","ready":true}

Соединение принимает только текстовые кадры в кодировке UTF-8, слушает локальный интерфейс и проверяет пропуск, переданный в адресе подключения. Сразу после соединения приходит та же строка готовности, что и при обмене через стандартный ввод-вывод.

Конверт запроса и ответа

interface Request { id?: unknown; cmd: SessionCommandName; /* command fields flattened */ }
interface Response<T=unknown> { id:unknown; ok:boolean; cmd?:string; elapsed_ms?:number; result?:T; error?:string; }

Ситуация	Что приходит
Запрос не объект или без поля `cmd`	`ok: false`, в поле `error` — `each request line must be a JSON object with a string cmd field`
Команды с таким именем нет	`ok: false`, в `error` — `unknown session command: <имя>`
Команда требует открытого документа	`ok: false`, в `error` — `no document is open in this session`
Внутренняя ошибка обработки	`ok: false` и сообщение с пометкой `panicked`. Сеанс при этом остаётся живым, соединение не рвётся — можно отправлять следующую команду

Версии контрактов обмена

Контракт	Версия
Машинное описание протокола сеанса	fastdoc.session-protocol-descriptor.v1
Готовность сеанса JSONL	fastdoc.session-serve.v1
Адрес и пропуск для WebSocket	fastdoc.session-ws-bootstrap.v1
Запуск поверхности: адрес, пропуск, версия	fastdoc.surface-host-bootstrap.v1
Вставка поверхности в вашу страницу	fastdoc.surface-mount.v1
Событие поверхности вашему приложению	fastdoc.surface-host-event.v1
Контекст взаимодействия — предлагается	`a4.interaction-context.v1`, ещё не зафиксирован