поверхность: черновики, статистика сессии, обрезка журнала, живой ход #8

Open
svuvich wants to merge 1 commit from surface-web into master
Owner

Что это

Бэкенд поверхности, который нужен веб-клиенту на Solid (PR
svuvich/snens-web#2). Ядро, журнал и конфиг не тронуты: всё, что здесь есть,
другим поверхностям (TUI, telegram) не нужно.

Маршруты

  • GET /v1/drafts — все черновики: {"drafts":[{id,text,updated_at}]}.
  • PUT /v1/drafts/{id} — {"text"}; пустой текст = удаление.
  • GET /v1/sessions/{id}/stats — итоги сессии.
  • POST /v1/sessions/{id}/truncate — {"seq"}: отрезать журнал от реплики
    человека.

Зачем каждое

Черновики. Начатое сообщение должно продолжаться на другом устройстве —
localStorage этого не умеет по определению. Храним в SQLite поверхности (не в
журнале сессии и не в конфиге: это состояние интерфейса). Ключ — id сессии
или new:<поверхность> для ещё не созданной: пустых сессий в журнале быть не
должно, а черновик новой сессии клиент показывает отдельной строкой в списке.

Статистика. Человек спрашивает про сессию целиком: сколько ходов, сколько
стоило, какой кеш-хит-рейт, сколько модель и тулы реально работали. В клиенте
это считать нельзя — перезагрузка окна обнуляла бы цифры, а второй клиент не
видел бы насчитанного первым. Активное время — единственное число, которого нет
в журнале готовым: сумма длительностей ходов по записям Done плюс текущий ход.

Обрезка. Правка реплики человека означает «переиграть ход с этого места»:
журнал режется по записи User, текст возвращается в композер. Без этого
маршрута правка была бы только косметикой.

Живой ход

GET …/history теперь отдаёт два поля: live — события текущего хода с
дельтами текста и рассуждения, и run_started — время старта хода. Журнал
пополняется записями по границам шагов, поэтому клиент, открытый посреди хода,
видел только их и терял начало рассуждения до перезагрузки. Буфер живёт в
памяти Runtime, заполняется в build_event по границам
run.started/run.finished и чистится на конце хода; на диск не пишется.

Проверки

  • cargo fmt --check — чисто; cargo clippy --all-targets — без новых
    предупреждений; cargo test --bin snens surface — 80 тестов, все зелёные.
  • Тесты на каждый маршрут: границы обрезки (не на User, вне диапазона,
    после обрезки), пустой черновик как удаление, чужой ключ — 400, статистика с
    пустым журналом и с незакрытым ходом, буфер хода собирает дельты и чистится.
  • Живой прогон с клиентом: полный ход с четырьмя вызовами run, перезагрузка
    посреди хода — лента собирается из live, после хода live пуст.
  • Контракты описаны в site/snens.svuvi.ch/content/api.md.
## Что это Бэкенд поверхности, который нужен веб-клиенту на Solid (PR svuvich/snens-web#2). Ядро, журнал и конфиг не тронуты: всё, что здесь есть, другим поверхностям (TUI, telegram) не нужно. ## Маршруты - `GET /v1/drafts` — все черновики: `{"drafts":[{id,text,updated_at}]}`. - `PUT /v1/drafts/{id}` — `{"text"}`; пустой текст = удаление. - `GET /v1/sessions/{id}/stats` — итоги сессии. - `POST /v1/sessions/{id}/truncate` — `{"seq"}`: отрезать журнал от реплики человека. ## Зачем каждое **Черновики.** Начатое сообщение должно продолжаться на другом устройстве — localStorage этого не умеет по определению. Храним в SQLite поверхности (не в журнале сессии и не в конфиге: это состояние интерфейса). Ключ — id сессии или `new:<поверхность>` для ещё не созданной: пустых сессий в журнале быть не должно, а черновик новой сессии клиент показывает отдельной строкой в списке. **Статистика.** Человек спрашивает про сессию целиком: сколько ходов, сколько стоило, какой кеш-хит-рейт, сколько модель и тулы реально работали. В клиенте это считать нельзя — перезагрузка окна обнуляла бы цифры, а второй клиент не видел бы насчитанного первым. Активное время — единственное число, которого нет в журнале готовым: сумма длительностей ходов по записям `Done` плюс текущий ход. **Обрезка.** Правка реплики человека означает «переиграть ход с этого места»: журнал режется по записи `User`, текст возвращается в композер. Без этого маршрута правка была бы только косметикой. ## Живой ход `GET …/history` теперь отдаёт два поля: `live` — события текущего хода с дельтами текста и рассуждения, и `run_started` — время старта хода. Журнал пополняется записями по границам шагов, поэтому клиент, открытый посреди хода, видел только их и терял начало рассуждения до перезагрузки. Буфер живёт в памяти `Runtime`, заполняется в `build_event` по границам `run.started`/`run.finished` и чистится на конце хода; на диск не пишется. ## Проверки - `cargo fmt --check` — чисто; `cargo clippy --all-targets` — без новых предупреждений; `cargo test --bin snens surface` — 80 тестов, все зелёные. - Тесты на каждый маршрут: границы обрезки (не на `User`, вне диапазона, после обрезки), пустой черновик как удаление, чужой ключ — 400, статистика с пустым журналом и с незакрытым ходом, буфер хода собирает дельты и чистится. - Живой прогон с клиентом: полный ход с четырьмя вызовами `run`, перезагрузка посреди хода — лента собирается из `live`, после хода `live` пуст. - Контракты описаны в `site/snens.svuvi.ch/content/api.md`.
Три маршрута в бэкенд поверхности — то, что нужно веб-клиенту и не нужно
ядру:

- `GET/PUT/DELETE /v1/drafts` — черновики сообщений в SQLite поверхности.
  Черновик обязан продолжаться на другом устройстве, поэтому он не в
  localStorage; ключ — id сессии или `new:<поверхность>` для ещё не
  созданной.
- `GET /v1/sessions/{id}/stats` — итоги сессии по журналу: ходы, шаги,
  вызовы, токены, цена, активное время (сумма длительностей ходов плюс
  текущий), кеш-хит-рейт. Считается на бэкенде, чтобы переживало
  перезагрузку окна и совпадало у разных клиентов.
- `POST /v1/sessions/{id}/truncate` — отрезать журнал от реплики человека:
  правка сообщения с повтором.

Плюс `history` отдаёт `live` — события текущего хода с дельтами, и
`run_started`: без них клиент, открытый посреди хода, видел только
записи по границам шагов. Буфер живёт в памяти поверхности и чистится на
конце хода.

Ядро (журнал, ходы, конфиг) не тронуто; тесты поверхности — на каждый
маршрут, включая границы обрезки и пустой черновик как удаление.
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin surface-web:surface-web
git switch surface-web

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch master
git merge --no-ff surface-web
git switch surface-web
git rebase master
git switch master
git merge --ff-only surface-web
git switch surface-web
git rebase master
git switch master
git merge --no-ff surface-web
git switch master
git merge --squash surface-web
git switch master
git merge --ff-only surface-web
git switch master
git merge surface-web
git push origin master
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
svuvich/snens!8
No description provided.