Queue Для Разработчика

НАЧАЛО >> Queue Для Разработчика📄 Скачать в DOCX

Модуль Queue является общесистемным runtime-слоем фонового выполнения. Он хранит задания, управляет их состоянием, retry-политикой, расписанием запуска, дедупликацией на уровне задания, dead-letter диагностикой и техническим контекстом выполнения. Доменные правила остаются в модулях-владельцах.

1. Handler Definition

Модуль-владелец регистрирует handler через RegisterHandlerDefinition. Handler описывает:

стабильный ключ handler-а;
модуль-владелец;
action, который будет выполнять задание;
версию контракта;
канал выполнения;
класс операции;
timeout;
retry-policy;
признаки cancelable, idempotent, progressAware и requiresSecurityRecheck;
схему payload и дополнительную metadata.

Queue не интерпретирует бизнес-смысл payload. Если задание меняет доменные записи, повторная проверка прав и актуального состояния должна выполняться handler-ом модуля-владельца.

2. Постановка Задания

Для постановки задания по зарегистрированному handler-у используется AppendRegisteredJob($handlerKey, $payload, $options). Метод нормализует параметры Queue и затем вызывает штатный Append.

В options можно передать:

queueTraceId или traceId для связи с TraceContext;
queueIdempotencyKey или idempotencyKey для технической дедупликации задания;
queueSourceRef для безопасной ссылки на источник задания;
queueChannelKey для выбора разрешенного канала;
scheduledAt для отложенного запуска;
timeout, donetimeout, restartonerror, max_retries при необходимости переопределения runtime-параметров.

Queue строит queuePayloadFingerprint по стабильной части payload/options. Trace id, время создания, session/csrf и похожие нестабильные поля в fingerprint не входят.

3. Idempotency

Queue отвечает только за техническую idempotency фонового задания. Бизнес-idempotency событий, переходов workflow, импорта или внешней интеграции остается у соответствующего owner-модуля. Например, EventBus отвечает за idempotency события, а Queue отвечает за повторное выполнение delivery-job.

4. Безопасность Данных

Payload задания не должен содержать пароли, токены, cookie и другие секреты. При построении runtime context и dead-letter записи Queue маскирует очевидные секретные поля. Если handler-у нужен секрет, в payload передается ссылка на запись Secrets, а сам секрет получает модуль-владелец через штатный защищенный контракт.

5. Dead Letter

BuildDeadLetterEntry формирует диагностическую запись по заданию, причине и деталям. MoveJobToDeadLetter переводит задание в fatal-состояние и сохраняет dead-letter envelope в result. Ручной повтор допустим только после проверки актуальности handler-а, payload, прав и доменного состояния.

6. HealthCheck И TestA

HealthCheck_Self возвращает provider-результат Queue: наличие QueueInfo.db, базовую схему таблицы data, наличие runtime registry и доступность системных JSON-описаний.

Safe-read TestA-проверка Queue покрывает загрузку модуля, регистрацию handler/channel, нормализацию задания, fingerprint, runtime context, dead-letter envelope, JSON-описания и HealthCheck. Write-проверки Queue остаются отдельными изолированными сценариями.