Терміни, затримка та ідемпотентність
1. Чому важливий спеціальний компонент опитування
Робочі процеси з підтримкою ШІ, які надсилають лист підтвердження (або вебхук‑колбек), за своєю природою асинхронні. У тестовому середовищі нам потрібно довести, що очікуваний доказ – прапорець “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‑вебхук або провайдерів‑моків у пам’яті.
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, але читає з розкладу в пам’яті, дозволяючи детерміновані тести без реального поштового трафіку.
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‑конвеєру виконати повний цикл poll‑validate за мілісекунди, ловлячи регресії часу до їх потрапляння у продакшн.
- Мінімальне логування даних – Структуровані журнали можна індексувати для сповіщень без розкриття вмісту користувачів, задовольняючи вимоги конфіденційності й зберігаючи трасуваність.
- Повторне використання між провайдерами – Оскільки логіка опитування не залежить від провайдера, той самий набір тестів валідовує Gmail, SendGrid або внутрішній вебхук лише зі зміною тонкого адаптера.
- Масштабована матриця тестів – Параметризуючи
deadline_secondsтаmax_attempts, команди можуть генерувати матрицю тестів «строгих» та «м’яких» SLA, автоматизуючи аналіз ризиків для різних угод про рівень сервісу.
11. Висновок
Добре спроектований компонент опитування перетворює вроджено нестабільний асинхронний крок верифікації у детермінований, тестований будівельний блок. Зафіксувавши всі часові обчислення на time.monotonic(), застосувавши обмежений експоненціальний бекофф із заздалегідь визначеним джиттером і забезпечивши ідемпотентність через стабільні ідентифікатори повідомлень, ми отримуємо:
- Передбачувані запуски CI – без прихованих залежностей від реального часу.
- Чітка семантика помилок – типізовані результати помилок спрощують налагодження.
- Приватність‑перша спостережливість – журнали містять лише мета‑інформацію.
Інтеграція цього компонента в ШІ‑орієнтовані робочі процеси перевірки електронної пошти дає інженерам QA впевненість, що сигнал «електронна пошта підтверджена» є як реальним, так і відтворюваним, при цьому тестовий набір залишається швидким, надійним і підтримуваним.
12. Питання для перегляду
- Чому time.monotonic() переважає над
time.time()для розрахунку дедлайнів у циклі опитування? - Як насіння генератора випадкових чисел за кількістю спроб робить джиттер детермінованим у тестах?
- Який механізм запобігає обробці сервісом опитування одного і того ж повідомлення про верифікацію більше одного разу?
- Перерахуйте два типи інформації, які ніколи не повинні з’являтися у структурованих журналах згідно з дизайном.
- У наданих юніт‑тестах, як симулюється сценарій «без корисного навантаження» провайдера без зовнішніх сервісів?
Залишити коментар
Поділіться думкою про статтю. Реєстрація не потрібна.
Коментарі
Завантаження коментарів…