Дедлайны, откат и идемпотентность
1. Почему важен отдельный компонент опроса
Рабочие процессы с поддержкой ИИ, отправляющие письмо‑подтверждение (или webhook‑коллбек), по своей природе асинхронны. В тестовой среде нам нужно доказать, что ожидаемый доказательство — флаг «verified», URL‑чека или подписанный токен — появляется в разумные сроки, не раскрывая персональные данные в логах и избегая нестабильных таймингов. Переиспользуемый сервис опроса предоставляет:
- Детерминированные дедлайны — измеряются с помощью time.monotonic(), поэтому часы не могут идти назад.
- Ограниченные повторения — экспоненциальный откат с джиттером предотвращает перегрузку провайдера, одновременно гарантируя максимальное время ожидания.
- Идемпотентная обработка — одинаковый ID сообщения игнорируется после первой успешной валидации, что устраняет дублирование обработки в шумных ящиках.
- Тестируемость — фейковые часы и фейковый провайдер позволяют проверять каждую ветку без реальных сетевых вызовов.
В следующих разделах рассматривается минимальная, с небольшим количеством зависимостей реализация, удовлетворяющая этим целям и её можно добавить в CI‑конвейер, использующий Playwright, pytest или любой другой тест‑раннер.
2. Обзор потока данных
Test / CI step
│
├─► ProviderAdapter (e.g. Gmail, SendGrid, mock HTTP)
│ – abstracts transport, returns raw payloads
│
├─► PollingService
│ – drives the deadline loop, backoff, deduplication
│
├─► Validator
│ – parses the payload, checks signatures, extracts DTO
│
└─► EvidenceResult
– success / typed error → Playwright or CI assertionАдаптер провайдера знает только как получить сообщение; сервис опроса знает когда остановиться; валидатор знает что считается валидным подтверждением.
Разделение ответственности делает компонент переиспользуемым для SMTP, REST‑webhook или провайдеров‑моков в памяти.
3. Основные DTO и типизированная модель ошибок
from dataclasses import dataclass
from typing import Literal, Union
@dataclass(frozen=True)
class VerificationDTO:
message_id: str # stable identifier from the provider
user_email: str
verified_at: float # epoch seconds, monotonic‑compatible
token: str # opaque, never logged
# Typed error outcomes – useful for CI reporting
PollResult = Union[
VerificationDTO,
Literal["timeout"],
Literal["malformed"],
Literal["duplicate"],
Literal["provider_error"]
]DTO неизменяемый, что делает его безопасным для совместного использования между потоками или асинхронными задачами. Литералы ошибок явные, чтобы тест мог точно проверить режим сбоя.
4. Контракт адаптера провайдера
from abc import ABC, abstractmethod
from typing import Optional, Dict, Any
class ProviderAdapter(ABC):
"""Transport‑level abstraction. Implementations must be side‑effect free
for a given `since` timestamp and return at most one payload per call."""
@abstractmethod
def fetch_latest(self, since: float) -> Optional[Dict[str, Any]]:
"""Return the raw payload received after `since` (monotonic seconds)
or `None` if no new message is available."""Конкретный адаптер Gmail преобразует сырое MIME‑сообщение в словарь, но логика опроса никогда не видит детали HTTP или IMAP.
5. Детерминированный сервис опроса
import os
import time
import random
import logging
from typing import Set
logger = logging.getLogger("polling")
logger.setLevel(logging.INFO)
class PollingService:
def __init__(
self,
provider: ProviderAdapter,
*,
max_attempts: int = 7,
base_delay: float = 0.5, # seconds
max_delay: float = 5.0,
jitter: float = 0.1, # fraction of delay
deadline_seconds: float = 30.0,
) -> None:
self.provider = provider
self.max_attempts = max_attempts
self.base_delay = base_delay
self.max_delay = max_delay
self.jitter = jitter
self.deadline_seconds = deadline_seconds
self._seen_ids: Set[str] = set()
def _next_delay(self, attempt: int) -> float:
"""Bounded exponential backoff with deterministic jitter."""
exp = min(self.base_delay * (2 ** attempt), self.max_delay)
# deterministic jitter – use a seeded RNG that tests can control
rng = random.Random(attempt) # seed = attempt number
jitter = rng.uniform(-self.jitter, self.jitter) * exp
return max(0.0, exp + jitter)
def poll(self, start_time: float) -> PollResult:
"""Run the deadline‑safe loop. Returns a DTO or a typed error."""
deadline = start_time + self.deadline_seconds
attempt = 0
while True:
now = time.monotonic()
if now >= deadline:
logger.info("polling timeout", extra={"deadline": deadline})
return "timeout"
raw = self.provider.fetch_latest(since=start_time)
if raw:
# Idempotency check – stable message_id must be unique
msg_id = raw.get("message_id")
if not msg_id:
logger.warning("malformed payload missing message_id")
return "malformed"
if msg_id in self._seen_ids:
logger.info("duplicate message ignored", extra={"msg_id": msg_id})
return "duplicate"
self._seen_ids.add(msg_id)
# Delegate validation
dto_or_error = Validator.validate(raw)
if isinstance(dto_or_error, VerificationDTO):
logger.info("verification received", extra={"msg_id": msg_id})
return dto_or_error
else:
logger.warning("payload failed validation")
return dto_or_error
# No payload yet – backoff before next attempt
delay = self._next_delay(attempt)
logger.debug("backoff", extra={"attempt": attempt, "delay": delay})
time.sleep(delay)
attempt += 1
if attempt >= self.max_attempts:
logger.info("max attempts reached without payload")
return "timeout"Ключевые моменты
- Безопасность дедлайна —
deadline = start + deadline_secondsиспользует time.monotonic(); цикл никогда не превышает предел, так как проверка происходит перед каждой паузой. - Deterministic jitter – генератор случайных чисел инициализируется номером попытки, гарантируя одинаковую последовательность в модульных тестах.
- Idempotency – набор наблюдаемых
message_idпредотвращает двойную обработку одной и той же проверки. - Structured logs – словари
extraсодержат только идентификаторы; реальное тело письма или токен никогда не появляются в выводе логов. - Secret handling – любые учётные данные, необходимые конкретному провайдеру, читаются из переменных окружения (
os.getenv) внутри реализации провайдера, никогда внутри ядра опроса.
6. Логика валидации
class ValidationError(RuntimeError):
pass
class Validator:
@staticmethod
def validate(raw: dict) -> Union[VerificationDTO, str]:
"""
Expected keys: message_id, user_email, verified_at, token.
Returns a DTO on success or a typed error literal.
"""
required = {"message_id", "user_email", "verified_at", "token"}
if not required.issubset(raw):
return "malformed"
try:
verified_at = float(raw["verified_at"])
# Additional domain‑specific checks could go here,
# e.g. signature verification, email format, etc.
return VerificationDTO(
message_id=raw["message_id"],
user_email=raw["user_email"],
verified_at=verified_at,
token=raw["token"],
)
except (ValueError, TypeError):
return "malformed"Валидатор остаётся чистым – без ввода‑вывода и сетевых вызовов – что делает его тривиальным для модульного тестирования в изоляции.
7. Пример использования в CI‑тесте
import pytest
def test_email_verification_flow():
# Arrange – fake provider that will emit a payload after 1.2 s
fake_provider = FakeProvider(
schedule=[
(1.2, {
"message_id": "msg-123",
"user_email": "alice@example.com",
"verified_at": str(time.monotonic() + 1.2),
"token": "opaque‑value"
})
]
)
poller = PollingService(fake_provider, deadline_seconds=5.0)
# Act
result = poller.poll(start_time=time.monotonic())
# Assert
assert isinstance(result, VerificationDTO)
assert result.message_id == "msg-123"
assert result.user_email == "alice@example.com"FakeProvider (показан позже) соблюдает тот же контракт fetch_latest, но читает из расписания в памяти, позволяя проводить детерминированные тесты без реального email‑трафика.
8. Набор модульных тестов с фейковыми часами
class FakeClock:
"""A minimal monotonic clock that can be advanced manually."""
def __init__(self, start: float = 0.0):
self._now = start
def monotonic(self) -> float:
return self._now
def advance(self, seconds: float):
self._now += seconds
class FakeProvider(ProviderAdapter):
"""Emits pre‑programmed payloads based on the fake clock."""
def __init__(self, schedule: list[tuple[float, dict]]):
# schedule = [(delay_from_start, payload), ...]
self.schedule = schedule
self.start = None
def fetch_latest(self, since: float) -> Optional[dict]:
if self.start is None:
self.start = since
elapsed = time.monotonic() - self.start
for delay, payload in self.schedule:
if delay <= elapsed:
# Return once and then remove to simulate single delivery
self.schedule.remove((delay, payload))
return payload
return None
def test_timeout_behavior(monkeypatch):
fake_clock = FakeClock()
monkeypatch.setattr(time, "monotonic", fake_clock.monotonic)
# Provider never yields a payload
provider = FakeProvider(schedule=[])
poller = PollingService(provider, deadline_seconds=2.0, max_attempts=3)
result = poller.poll(start_time=fake_clock.monotonic())
assert result == "timeout"
def test_duplicate_delivery(monkeypatch):
fake_clock = FakeClock()
monkeypatch.setattr(time, "monotonic", fake_clock.monotonic)
payload = {
"message_id": "dup-001",
"user_email": "bob@example.com",
"verified_at": "0",
"token": "t"
}
provider = FakeProvider(schedule=[(0.1, payload), (0.5, payload)])
poller = PollingService(provider, deadline_seconds=5.0)
# First poll consumes the payload
first = poller.poll(start_time=fake_clock.monotonic())
assert isinstance(first, VerificationDTO)
# Advance clock – second poll sees the same message_id
fake_clock.advance(1.0)
second = poller.poll(start_time=fake_clock.monotonic())
assert second == "duplicate"
def test_malformed_payload(monkeypatch):
fake_clock = FakeClock()
monkeypatch.setattr(time, "monotonic", fake_clock.monotonic)
malformed = {"user_email": "carl@example.com"} # missing required keys
provider = FakeProvider(schedule=[(0.2, malformed)])
poller = PollingService(provider, deadline_seconds=3.0)
result = poller.poll(start_time=fake_clock.monotonic())
assert result == "malformed"monkeypatch(fixture pytest) заменяетtime.monotonicфейковыми часами, гарантируя детерминированное время.- Фейковый провайдер соблюдает тот же контракт, позволяя тестировать случаи тайм‑аутов, дубликатов и некорректных данных без внешних сервисов.
9. Чек‑лист QA для компонента опроса
- Безопасный дедлайн: Проверить, что
time.monotonic()используется для всех измерений прошедшего времени. - Границы задержки: Убедиться, что
max_delayне превышается даже после добавления случайного разброса. - Детерминированный разброс: Передавать или фиксировать источник случайности в модульных тестах и проверять точные интервалы ожидания.
- Идемпотентность: Проверить, что повторная полезная нагрузка с тем же
message_idвозвращаетduplicate. - Классификация ошибок: Проверить ожидаемые результаты
timeout,malformed,duplicateиprovider_error. - Изоляция секретов: Читать учётные данные из конфигурации окружения и никогда не записывать их в журналы.
- Безопасные журналы: Записывать только безопасные идентификаторы и данные времени, но не содержимое сообщений, токены или персональные данные.
- Разделение транспорта: Дедлайны, задержки и дедупликацию держать в
PollingService, а детали провайдера — в адаптерах. - Покрытие тестами: Проверить успех, тайм-аут, дубликат, некорректную нагрузку и ошибку провайдера.
- Интеграция с CI: Проверять возвращённый
VerificationDTOнепосредственно из Playwright или другого сквозного теста.
10. Где автоматизация помогает
- Быстрое обнаружение регрессий – Детеминированный откат и фейковый часы позволяют CI‑конвейеру выполнять полный цикл опрос‑валидация за миллисекунды, ловя регрессии таймингов до их попадания в продакшн.
- Логирование с минимальными данными – Структурированные логи можно индексировать для оповещений без раскрытия пользовательского контента, удовлетворяя требования конфиденциальности и обеспечивая трассируемость.
- Кросс‑провайдерное переиспользование – Поскольку логика опроса независима от провайдера, один и тот же набор тестов проверяет Gmail, SendGrid или внутренний webhook, меняя лишь тонкий адаптер.
- Масштабируемая тестовая матрица – Параметризуя
deadline_secondsиmax_attempts, команды могут генерировать матрицу тестов «строгих» vs. «свободных» SLA, автоматизируя анализ рисков для разных соглашений об уровне обслуживания.
11. Заключение
Тщательно спроектированный компонент опроса превращает по своей природе ненадёжный асинхронный шаг проверки в детерминированный, тестируемый строительный блок. Привязывая все расчёты времени к time.monotonic(), применяя ограниченный экспоненциальный откат с посеянным джиттером и обеспечивая идемпотентность через стабильные идентификаторы сообщений, мы получаем:
- Предсказуемые CI‑запуски – без скрытых зависимостей от настенных часов.
- Ясная семантика ошибок – типизированные результаты ошибок делают отладку простой.
- Наблюдаемость, ориентированная на конфиденциальность – журналы содержат только мета‑информацию.
Интеграция этого компонента в ИИ‑управляемые рабочие процессы проверки электронной почты даёт инженерам QA уверенность, что сигнал «email verified» является как реальным, так и воспроизводимым, при этом тестовый набор остаётся быстрым, надёжным и поддерживаемым.
12. Вопросы для обзора
- Почему time.monotonic() предпочтителен перед
time.time()для расчётов дедлайна в цикле опроса? - Как посев генератора случайных чисел числом попытки делает джиттер детерминированным в тестах?
- Какой механизм предотвращает обработку сервисом опроса одного и того же сообщения проверки более одного раза?
- Перечислите два фрагмента информации, которые никогда не должны появляться в структурированных журналах согласно дизайну.
- В предоставленных модульных тестах, как симулируется сценарий «без полезной нагрузки» провайдера без внешних сервисов?
Оставить комментарий
Поделитесь своим мнением о статье. Регистрация не требуется.
Комментарии
Загрузка комментариев…