ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Настроить message schema registry

1. Цель задачи

Научиться проектировать и развёртывать централизованное хранилище версий схем сообщений для многокомпонентной системы, где агенты (микросервисы) обмениваются данными. Создать registry, который автоматически проверяет совместимость новых версий схем с предыдущими и блокирует breaking changes на уровне CI/CD.

Ключевой результат Работающий schema registry + CI-check, который не пропускает обратно несовместимые изменения сообщений.

2. Исходные данные

Перед началом необходимо иметь:

Если нет реального инструмента — симулируем:

1. Вместо Kafka Schema Registry используем самописный Flask‑сервис, который хранит схемы в SQLite и предоставляет API:
   • POST /schemas — зарегистрировать новую схему
   • GET /schemas/{name}/versions — список версий
   • GET /schemas/{name}/versions/{version} — получить конкретную
   • POST /compatibility — проверить новую схему против последней
2. Для проверки совместимости используем Python‑библиотеки: jsonschema (для JSON Schema) или fastavro (для Avro).
3. CI‑шаг: скрипт, который загружает новую схему в registry и проверяет возвращаемый статус.

3. Технологический стек

4. Этапы выполнения

Этап 1: Разработка спецификаций схем (оценка: 30 минут)

Действия

1. Придумать 3–4 типа сообщений для системы (например, UserRegistered, OrderCreated, PaymentApproved).
2. Для каждого типа создать JSON Schema (файл .schema.json) и поместить в папку schemas/ репозитория.
   • Первая версия v1 с полями: id, timestamp, data.
   • Пример UserRegistered/v1.schema.json:

     {
       "$schema": "https://json-schema.org/draft-07/schema#",
       "type": "object",
       "properties": {
         "userId": {"type": "string"},
         "email": {"type": "string", "format": "email"},
         "registeredAt": {"type": "string", "format": "date-time"}
       },
       "required": ["userId", "email"]
     }
     

3. Для каждой схемы подготовить вторую версию (v2) — совместимую (добавлено опциональное поле phone) и третью версию (v3) — несовместимую (поле userId переименовано в user_id).

Ожидаемый результат этапа Папка schemas/ с как минимум 3 схемами по 2–3 версии каждая. Примеры: UserRegistered/v1.schema.json, UserRegistered/v2.schema.json, UserRegistered/v3.schema.json (несовместимая).

Этап 2: Создание Schema Registry Service (оценка: 2–3 часа)

Действия

1. Инициализировать Python‑проект (fastapi, uvicorn, sqlalchemy, jsonschema, pydantic).

2. Реализовать модели данных:

   • Schema (id, name, version, json_schema, created_at, is_latest)

3. Реализовать REST endpoints:

   Метод	Endpoint	Описание
   POST	/schemas	Регистрация новой схемы (тело: { name, version, json_schema })
   GET	/schemas/{name}/versions	Список всех версий для name
   GET	/schemas/{name}/versions/{version}	Получить конкретную схему
   POST	/compatibility	Проверить совместимость (тело: { name, json_schema })
   GET	/health	Health‑check

4. Реализовать логику совместимости:

   • Для JSON Schema: backward‑compatible = все поля из предыдущей версии присутствуют в новой (можно добавлять опциональные, нельзя удалять/переименовывать required).
   • Проверка:
     1. Загрузить последнюю зарегистрированную схему.
     2. Попробовать валидировать пример сообщения, удовлетворяющего предыдущей схеме, против новой — если ошибка, то несовместимо.
     3. Дополнительно можно сравнивать структуру (список required).
   • Принимать параметр compatibilityType (backward, forward, full); по умолчанию backward.

5. Запустить сервис локально через uvicorn app:app --reload. Протестировать через curl или httpie.

Ожидаемый результат этапа Работающий REST API registry, способный регистрировать схемы и возвращать совместимость.

Этап 3: CI‑check на совместимость (оценка: 1–2 часа)

Действия

1. Создать в корне репозитория скрипт ci_validate.py:

   • Читает все схемы из папки schemas/.
   • Для каждой схемы, которая изменена в PR (сравнить с main веткой), отправляет POST в registry на /compatibility.
   • Если ответ "compatible": false, то завершается с кодом 1 (fail).
   • Использует переменные окружения REGISTRY_URL (по умолчанию http://localhost:8000).

2. Настроить pipeline в GitHub Actions (файл .github/workflows/schema-check.yml):

   name: Schema Compatibility Check
   on:
     pull_request:
       paths: ['schemas/**']
   jobs:
     check:
       runs-on: ubuntu-latest
       services:
         registry:
           image: python:3.10
           ports: ['8000:8000']
           options: >-
             --health-cmd "curl -f http://localhost:8000/health"
             --health-interval 10s
             --health-timeout 5s
             --health-retries 3
       steps:
         - uses: actions/checkout@v3
         - name: Start registry
           run: |
             pip install -r requirements.txt
             uvicorn app:app --host 0.0.0.0 --port 8000 &
         - name: Register existing schemas (optional)
           run: python ci_bootstrap.py  # регистрирует текущие схемы
         - name: Validate changed schemas
           run: python ci_validate.py
           env:
             REGISTRY_URL: http://localhost:8000
   

3. Протестировать:

   • Создать ветку с несовместимым изменением (v3 схемы) → открыть PR → убедиться, что CI падает.
   • Создать ветку с совместимым изменением (добавить optional поле) → PR проходит.

Ожидаемый результат этапа GitHub Actions pipeline, который блокирует PR с breaking changes.

Этап 4: Документация и тестирование (оценка: 1 час)

Действия

1. Написать README.md с инструкцией:
   • Как запустить registry локально.
   • Как добавить новую схему.
   • Как работает CI‑процесс.
2. Написать unit‑тесты для сервиса (pytest):
   • Тест регистрации.
   • Тест backward‑compatible.
   • Тест breaking change.
   • Тест health.
3. Добавить конфигурацию Docker Compose (опционально):

   version: '3.8'
   services:
     registry:
       build: .
       ports: ['8000:8000']
   

Ожидаемый результат этапа README, unit‑тесты, возможность запустить одной командой docker-compose up.

Этап 5: Интеграционный тест с двумя агентами (оценка: 1 час)

Действия

1. Создать два простых симулятора агентов (Python скрипты agent_a.py, agent_b.py):
   • Агент A отправляет сообщение (тело через HTTP) в Agent B.
   • Агент B перед обработкой делает GET /schemas/{name}/versions/latest и валидирует входящее сообщение по схеме.
2. При изменении схемы (новый тег) агенты обновляют кешированные схемы.
3. Протестировать сценарий: агенты работают со старой схемой, затем registry обновляется с совместимой версией → агенты успешно обрабатывают сообщения. Затем обновление с несовместимой → обработка ломается (можно продемонстрировать fallback).
4. Зафиксировать результаты в отчёте.

Ожидаемый результат этапа Работающая демонстрация end‑to‑end с двумя агентами, использующими schema registry.

5. Критерии приемки (Definition of Done)

• Registry запускается локально одной командой (docker-compose up или python app.py).
• API регистрирует схемы и возвращает их по имени и версии.
• Эндпоинт /compatibility корректно определяет backward‑совместимость (добавление optional полей — совместимо; удаление required, переименование — несовместимо).
• CI‑pipeline (GitHub Actions) выполняет проверку при изменении схем в PR.
• PR с несовместимым изменением помечается как failed и мерж блокируется (либо в GitHub Actions статус fail).
• Написаны минимум 4 unit‑теста (регистрация, совместимость, несовместимость, health).
• README содержит инструкцию по запуску и описание формата схем.
• В репозитории присутствуют как минимум 3 схемы, каждая минимум с 2 версиями (совместимой и несовместимой).

6. Ожидаемый результат

• Артефакт 1 Исходный код Schema Registry (FastAPI/Flask + SQLite) в отдельном репозитории или модуле.
• Артефакт 2 Git‑репозиторий со схемами в папке schemas/ и CI‑конфигурацией .github/workflows/schema-check.yml.
• Артефакт 3 Скрипт ci_validate.py для использования в любом CI.
• Артефакт 4 README.md с документацией.
• Дополнительно Тестовые симуляторы агентов (agent_a.py, agent_b.py), демонстрирующие использование registry в runtime.

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание: Для первого раза время может увеличиться до 10–12 часов из‑за отладки CI и развёртывания.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я создал минимум 3 схемы с разными версиями (совместимые и несовместимые) и поместил их в schemas/.
• Я запустил сервис registry локально и протестировал все endpoints через curl.
• Я написал скрипт ci_validate.py и протестировал его локально против registry.
• Я настроил GitHub Actions, который запускает проверку при PR в папку schemas/.
• Я создал PR с несовместимым изменением схемы и убедился, что CI падает (статус fail).
• Я убедился, что PR с совместимым изменением проходит успешно.
• Я написал README с инструкцией по запуску и использованию registry.
• Я добавил юнит‑тесты для сервиса и они проходят.
• Я опционально написал Docker Compose и протестировал docker-compose up.
• Я реализовал (хотя бы в тестовом режиме) интеграцию с двумя агентами, чтобы показать end‑to‑end workflow.