Open source · Apache 2.0↗

Неизменяемая история
каждой сущности.

Letopis хранит каждое изменение каждого объекта в вашей системе — с защитой от подделки черезSHA-256 хэш-цепи, восстановлением состояния в любой момент времени и условными вебхуками. REST + gRPC. Мультитенантность. Self-hosted.

НачатьGitHub
letopis · быстрый старт
# API-ключ из config.yaml
TOKEN=hm_dev_plaintext

# Отправить состояние — сервер вычислит дифф
curl -s -X POST \
  http://localhost:8080/api/v1/collections/crm.deals/entities/deal-1/state \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"state": {"title": "ООО Ромашка", "amount": 50000}}'

# Прочитать историю
curl -s \
  http://localhost:8080/api/v1/collections/crm.deals/entities/deal-1/history \
  -H "Authorization: Bearer $TOKEN"
Стек
Go 1.25+·MongoDB 7+·Redis 6+·gRPC + REST·Apache 2.0

Возможности

Всё необходимое для аудит-уровневой истории

От защищённого от подделки хранилища до условных вебхуков — Letopis даёт полноценную production-ready инфраструктуру журнала аудита.

Хэш-цепи

SHA-256 связывание событий делает незаметное изменение или удаление немедленно обнаруживаемым. Верификация через эндпоинт :verify.

Point-in-time чтение

Восстановление точного состояния сущности на любую прошлую версию или момент времени. p99 менее 7 мс для историй из 10 000 версий.

Два режима ingest

Отправляйте полное состояние объекта и позвольте Letopis вычислить дифф, или отправляйте готовый дифф напрямую. Оба варианта дают одинаковые события.

Три режима надёжности

Выбор на уровне запроса: strict (синх. 201), durable (Redis 202),fast (in-memory 202). Тикеты для отслеживания асинхронных записей.

Правила и вебхуки

Условные правила запускают подписанные HTTP-коллбэки при каждом подходящем изменении. Dead-letter очередь для недоставленных сообщений.

Мультитенантность

Жёсткая изоляция на уровне базы данных MongoDB для каждого тенанта. Маршрутизация по API-ключу — ID тенанта не фигурирует в URL.

Как это работает

Три шага от записи до запроса

01

Ingest

Ваша система отправляет текущее состояние сущности или готовый дифф. Letopis валидирует, нормализует и ставит запись в очередь с выбранным режимом надёжности.

02

Хранение

События записываются append-only в MongoDB. Плагин SHA-256 хэш-цепи связывает каждое событие с предыдущим. Каждые 100 событий материализуется слепок для быстрого чтения.

03

Запрос

Читайте текущее состояние, постраничную историю или восстанавливайте состояние на любую прошлую версию. Бизнес-потоки связывают события через коллекции в причинно-следственные DAG.

Быстрый старт

Запуск за несколько минут

1

Сборка из исходников

Требования: Go 1.25+, MongoDB 7+, Redis 6+.

2

Настройка тенантов

Скопируйте config.example.yaml, установите ID тенанта и API-ключ.

3

Запись и чтение

Отправьте первое изменение через REST. Используйте GET /history для проверки.

# Или скачать готовый бинарь: github.com/max-trifonov/letopis/releases
# Клонировать и собрать
git clone https://github.com/max-trifonov/letopis.git
cd letopis && make build

# Настроить
cp config.example.yaml config.yaml

# Запустить
./bin/letopis serve

# Или через Docker Compose
docker compose -f docker-compose.dev.yml up --build

Клиентские SDK

Типизированные клиенты под ваш стек

Не собирайте HTTP-запросы вручную — официальные SDK оборачивают REST API билдерами запросов и интеграцией с фреймворком.

Laravel SDK

PHP 8.2+ · Laravel 11/12
// Eloquent-обсервер записывает изменения автоматически
Letopis::ingest('crm.deals', 'd-1')
  ->authorId('42')
  ->state(['amount' => 250]);
composer require letopis/laravel-sdk →

Node SDK

Node.js 18+ · TypeScript
// Без рантайм-зависимостей, нативный fetch
await letopis.ingest('crm.deals', 'd-1')
  .authorId('42')
  .state({ amount: 250 })
npm install letopis-node →

Применение

Для команд, которым важна подотчётность

📊

CRM и продажи

Полная история каждой сделки, контакта и изменения статуса. Знайте, кто и когда внёс изменение.

📄

Договоры и документы

Защищённая от подделки история версий каждого соглашения. Восстановление любой редакции для разрешения споров.

💰

Финансы и комплаенс

Неизменяемый журнал изменений балансов и транзакций. Готово для регуляторного аудита по дизайну.

⚙️

Конфигурация и инфраструктура

Отслеживание каждого изменения конфигурации и состояния инфраструктуры с атрибуцией автора.

Open source

Разрабатывается открыто

Letopis распространяется под лицензией Apache 2.0. Вклад в проект приветствуется — каждый коммит требует DCO sign-off. Значимые изменения лучше обсудить в issue перед написанием кода. Публичное Go API — pkg/ext; внутренние пакеты не стабилизированы.

Звезда на GitHubРуководство по участию →
Apache 2.0
Лицензия
Go 1.25+
Язык
DCO
Обязателен sign-off
pkg/ext
Стабильный API

Готовы отслеживать каждое изменение?

Установите Letopis за несколько минут и начните строить аудит-уровневую историю.

Начать →Документация