walgit: Git-хостинг на WAL и объектном хранилище

Git — распределённая система, и именно это делает его хостинг неудобным по одной причине: packfiles (упакованные файлы). Всё содержимое репозитория сжимается в крупные бинарные паки, оптимизированные под компактность, а не под последовательное чтение; любая операция git — это случайный обход гигабайт данных. На ноутбуке, где файл находится в кэше страниц, это терпимо, а по сетевой файловой системе — катастрофа: именно поэтому подход «просто положить репозитории на NFS» провалился у всех крупных хостингов, кто его пробовал. Выжившая архитектура (GitHub Spokes) хранит настоящие репозитории на локальных NVMe-дисках, чтобы сам git делал всю работу, и реплицирует на уровне packfile с жёсткими гарантиями согласованности — ценой трёхфазного коммита через фиксированный набор реплик, базы данных с маппингом каждого репозитория на его машины и парка «питомцев» (pets).

Ключевая идея Continuity меняет экономику: сделать журнал с упреждающей записью (write-ahead log, WAL) в объектном хранилище единственным источником истины, а любой репозиторий на диске — лишь кэшем. Push сохраняется как неизменяемый объект в бакете и становится виден только после атомарной перезаписи небольшого манифеста через compare-and-swap (CAS). Этот CAS и есть консенсус — без выборов лидера, без кворума, без первичного узла. Принять push может любой экземпляр; два конкурирующих экземпляра не могут победить оба. Реплика, которая никогда не видела репозитория, читает лог и получает его целиком. Чтение согласованно без координации, потому что каждый запрос сначала проверяет у хранилища, изменилось ли что-либо (условный GET, обычно возвращающий 304). Уплотнение (compaction) выполняет ровно один экземпляр, удерживающий аренду, и публикует результат в лог — реплики скачивают уже уплотнённые паки вместо того, чтобы переупаковывать самостоятельно. А поскольку WAL является истиной, каждое действие задокументировано: каждый push и каждый repack воспроизводимы до любой точки.

walgit берёт эту архитектуру как есть и добавляет то, что нужно монорепозиторию на небольших машинах: отдача refs и веб-страниц для репозитория, чьи паки никогда не поместятся на экземпляре (режим remote reader через HTTP range requests), хранение коммитов и деревьев локально при том, что блобы остаются в бакете (режим history pack), и перенос байт клонирования полностью за пределы сервера (bundle-uri: свежие клоны и обновления раздаются как статические файлы из бакета или CDN).

Репозиторий — это WAL в бакете. Под repos/<owner>/<repo>/: manifest.pb (маленький, перезаписывается через CAS: порядковый номер головы, набор живых паков, указатель на чекпоинт, настройки — точка линеаризации), log/<seq>.pb (неизменяемые записи: PUSH, COMPACT, CHECKPOINT, SETTINGS), wal/<checksum>.pack|.idx|.rev|.bitmap|.commit-graph (неизменяемые, content-addressed паки с сопутствующими файлами), checkpoints/<seq>/ (свёрнутый снимок refs + опись паков для холодного старта — снимок плюс хвост лога), bundles/, leases/ (CAS с TTL — единственный кросс-экземплярный мьютекс), policy.json, lfs/objects/, events/cursor.json.

Push: наш receive-pack индексирует пак (git index-pack --fix-thin --rev-index во временной директории), проверяет связность и политики, загружает pack ∥ idx ∥ log entry, а затем выполняет CAS манифеста. При ответе 412 перечитывает манифест, повторно проверяет старые значения каждого ref и повторяет попытку. Конкурирующие push в один репозиторий на одном экземпляре группируются в один CAS. Клиент видит ok только после того, как бакет подтвердил запись.

Чтение: один условный GET манифеста; 304 → отдаём из локальной копии, 200 → применяем новые записи. Что именно означает «применить» — зависит от того, что нужно запросу: refs (снимок + лог → packed-refs, без паков: объявления, API, списки бандлов), serve (набор паков в объёме, который данная машина может хранить: небольшие паки и history pack локально, слишком большая база читается range-запросом), full (всё локально, для repack), objects (remote reader, для UI на репозитории, который не помещается целиком). Загрузки паков идут в собственном рантайме и никогда не блокируют запрос refs.

Размещение — это конфигурация. Glob-паттерны [placement] serve / maintain указывают, для каких репозиториев хост выполняет объектную работу; чтение на уровне refs работает везде. Один сервер: оставьте значения по умолчанию. Несколько: поместите монорепозиторий на хост с SSD (cache.mode = "disk"), остальное — на маленькие машины, и маршрутизируйте по /<owner>/<repo> перед ними.

Ничто не ждёт молча. Всё медленное — это задача (task) с идентификатором, логом и потоком прогресса — нарратив отправляется в git по sideband 2 (remote: * …) и в браузер через SSE.

AGENTS.md — это полная архитектурная документация и руководство оператора: ограничения, стратегии WAL, каждое проектное решение с обоснованием, инварианты и модель стоимости (бюджет — количество round-trip’ов к бакету).

Роли (server.roles): serve (git, API, UI, бандлы, LFS), maintain (чекпоинты, бандлы, уплотнение, fsck/восстановление), events (мост вебхуков). Пусто = все. Любое количество хостов с ролью serve может смотреть на один бакет; назначьте каждому репозиторию одного мейнтейнера (glob-паттерны размещения) — и готово.

MIT — см. LICENSE.